Creazione di una configurazione API

Prerequisiti

Prima di poter creare una configurazione API, assicurati di avere:

• Aver preparato l'ambiente di sviluppo come descritto in Configurazione dell'ambiente di sviluppo.

• Creazione di una definizione API come specifica OpenAPI.

• Se vuoi, hai creato un'API come descritto nella sezione Creazione di un'API. Se l'API non esiste già, viene creata dalla configurazione API.

Requisiti dell'ID configurazione API

Molti dei comandi gcloud mostrati di seguito richiedono di specificare l'ID della configurazione API nel formato CONFIG_ID. API Gateway applica i seguenti requisiti per l'ID configurazione API:

• Deve avere una lunghezza massima di 63 caratteri.
• Deve contenere solo lettere minuscole, numeri o trattini.
• Non deve iniziare con un trattino.
• Non deve contenere un trattino basso.

Creazione di una configurazione API

Utilizza Google Cloud CLI per caricare la definizione API e creare una configurazione API. Quando carichi la definizione dell'API, devi specificare il nome dell'API. Se l'API non esiste già in API Gateway, viene creata anche da questo comando.

Nota: API Gateway supporta la creazione di definizioni API come specifiche OpenAPI per tutti i servizi di backend disponibili. API Gateway supporta anche l'utilizzo di definizioni e configurazioni di servizio gRPC per i servizi gRPC su Cloud Run.

Per creare una configurazione API:

1. Cambia directory nella directory contenente la definizione dell'API.

   Per ulteriori informazioni sulla creazione della specifica OpenAPI per la definizione dell'API, consulta Panoramica di OpenAPI e Guida rapida: deployment di un'API su API Gateway.

   Per saperne di più sulla creazione di una definizione e configurazione di un servizio gRPC per la tua definizione API, consulta Configurazione di un servizio gRPC e Guida introduttiva ad API Gateway e Cloud Run for gRPC.

2. Convalida l'ID progetto restituito dal seguente comando per assicurarti che il servizio non venga creato nel progetto sbagliato.

   gcloud config list project

   Se devi modificare il progetto predefinito, esegui il comando seguente e sostituisci PROJECT_ID con l'ID del progetto Google Cloud in cui vuoi creare il servizio:

   gcloud config set project PROJECT_ID

3. Visualizza la guida per il comando api-configs create:

   gcloud api-gateway api-configs create --help

4. Esegui questo comando per creare la configurazione API:

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=API_DEFINITION \
     --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   dove:

   • CONFIG_ID specifica l'ID della nuova configurazione API.
   • API_ID specifica l'ID dell'API API Gateway associato a questa configurazione API. Se l'API non esiste già, viene creata da questo comando.
   • API_DEFINITION specifica il nome della specifica OpenAPI contenente la definizione dell'API.
   • PROJECT_ID specifica l'ID del progetto Google Cloud.
   • SERVICE_ACCOUNT_EMAIL specifica l'account di servizio utilizzato per firmare i token per i backend con autenticazione configurata. Per maggiori dettagli, vedi Configurare un account di servizio.

   Durante la creazione della configurazione dell'API e dell'API, API Gateway invia le informazioni al terminale. Il completamento di questa operazione potrebbe richiedere diversi minuti poiché la configurazione API viene propagata ai sistemi downstream. Il completamento della creazione di una configurazione API complessa potrebbe richiedere fino a dieci minuti. Durante la creazione di una configurazione, non tentare di crearne un'altra per la stessa API. È possibile creare una sola configurazione per ogni API alla volta.

5. Una volta completato il deployment, puoi utilizzare il comando seguente per visualizzare i dettagli della nuova configurazione API:

   gcloud api-gateway api-configs describe CONFIG_ID \
     --api=API_ID --project=PROJECT_ID

   Questo comando restituisce quanto segue:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
     backendConfig:
       googleServiceAccount: [e-mail]
   labels: ''
   name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
   serviceRollout:
     rolloutId: 2020-02-04r2
   state: ACTIVE
   updateTime: '2020-02-04T18:33:12.219323647Z'

6. Abilita l'API utilizzando il nome del servizio gestito dell'API. Puoi trovare questo valore nella colonna Managed Service (Servizio gestito) della tua API nella pagina di destinazione delle API:

   gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

   Devi eseguire questo comando solo una volta quando crei l'API. Se in un secondo momento modifichi l'API, non devi eseguire nuovamente il comando.

Google Cloud CLI prevede molte opzioni, incluse quelle descritte nella Guida di riferimento gcloud. Inoltre, per API Gateway, puoi impostare le seguenti opzioni quando crei una configurazione API:

• --async: restituisci immediatamente il controllo al terminale, senza attendere il completamento dell'operazione.
• --display-name=NAME: specifica il nome visualizzato della configurazione API, ovvero il nome mostrato nell'interfaccia utente. Non utilizzare spazi nel nome. Utilizza invece trattini e trattini bassi. Il valore predefinito è CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: specifica le etichette associate alla configurazione API.

Ad esempio:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

Puoi vedere le etichette nell'output del comando describe mostrato sopra o nel comando list includendo l'opzione --format:

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_ID --format="table(name, labels)"

Elenco delle configurazioni API

Per elencare le configurazioni API per un progetto specifico:

gcloud api-gateway api-configs list --project=PROJECT_ID

Questo comando restituisce quanto segue:

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

Per elencare le configurazioni API per un'API specifica in un progetto:

gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

Utilizza gli ID progetto, API e configurazione per ottenere informazioni dettagliate sulla configurazione API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

Aggiornamento di una configurazione API

Non puoi modificare una configurazione API esistente se non per aggiornare le relative etichette e il nome visualizzato.

Nota: ogni volta che carichi una definizione API, API Gateway crea una nuova configurazione API.

Per aggiornare una definizione API:

1. Aggiorna la specifica OpenAPI contenente la definizione dell'API.
2. Carica la definizione API per creare una nuova configurazione API.

Utilizza lo stesso comando per creare la nuova configurazione API utilizzata per creare la configurazione API iniziale, come illustrato sopra nella sezione Creazione di una configurazione API.

Utilizza il seguente gcloud per aggiornare una configurazione API esistente:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

Ad esempio:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_ID \
  --update-labels=a=1,b=2

Utilizza il seguente comando per visualizzare tutte le opzioni di aggiornamento:

gcloud api-gateway api-configs update --help

Eliminazione di una configurazione API

Avviso: se hai eseguito il deployment della configurazione API in un gateway, è possibile che la configurazione API non venga eliminata finché il gateway non utilizza più la configurazione API.

Prima di eliminare una configurazione API in uso, devi:

• Esegui il deployment di una configurazione API diversa nel gateway.
• Elimina il gateway.

Per ulteriori informazioni, consulta Deployment di un'API in un gateway.

Utilizza il seguente comando gcloud per eliminare una configurazione API esistente:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

Passaggi successivi

• Deployment di un'API a un gateway