Creazione di una configurazione API

Prerequisiti

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

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

• Hai creato una definizione dell'API come specifica OpenAPI.

• Se vuoi, crea un'API come descritto in Creazione di un'API. Se l'API non esiste già, viene creata quando viene creata la configurazione API.

Requisiti per l'ID configurazione API

Molti dei comandi gcloud riportati 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 dell'API e creare una configurazione dell'API. Quando carichi la definizione dell'API, devi specificare il nome dell'API. Se l'API non esiste già in API Gateway, questo comando la crea anche.

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

Per creare una configurazione API:

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

   Per saperne di più sulla creazione della specifica OpenAPI per la definizione dell'API, consulta la Panoramica di OpenAPI e la Guida rapida: esegui il deployment di un'API in API Gateway.

   Per scoprire di più sulla creazione e sulla configurazione di una definizione di servizio gRPC per la definizione dell'API, consulta Configurazione di un servizio gRPC e Introduzione ad API Gateway e Cloud Run per 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 seguente comando e sostituisci PROJECT_ID con l'ID 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 il comando seguente 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 associata a questa configurazione API. Se l'API non esiste già, questo comando la crea.
   • API_DEFINITION specifica il nome della specifica OpenAPI contenente la definizione dell'API.
   • PROJECT_ID specifica l'ID progetto Google Cloud.
   • SERVICE_ACCOUNT_EMAIL specifica l'account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata. Per maggiori dettagli, vedi Configurare un account di servizio.

   Durante la creazione dell'API e della configurazione API, API Gateway visualizza informazioni sul terminale. Il completamento dell'operazione potrebbe richiedere diversi minuti, poiché la configurazione dell'API viene propagata ai sistemi a valle. La creazione di una configurazione API complessa potrebbe richiedere fino a dieci minuti. Durante la creazione di una configurazione, non tentare di creare un'altra configurazione per la stessa API. È possibile creare una sola configurazione per volta per qualsiasi API.

5. Al termine, puoi utilizzare il seguente comando 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 per la tua API nella pagina di destinazione delle API:

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

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

Google Cloud CLI accetta molte opzioni, tra cui quelle descritte nella documentazione di riferimento di gcloud. Inoltre, per API Gateway puoi impostare le seguenti opzioni durante la creazione di una configurazione API:

• --async: restituisce immediatamente il controllo al terminale, senza attendere il completamento dell'operazione.
• --display-name=NAME: specifica il nome visualizzato della configurazione API, ovvero il nome visualizzato nell'interfaccia utente. Non utilizzare spazi nel nome. Utilizza i trattini e i trattini bassi. Il valore predefinito è CONFIG_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: specifica le etichette associate alla configurazione dell'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)"

Configurazioni API Listing

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, ma puoi aggiornarne le etichette e il nome visualizzato.

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

Per aggiornare una definizione di API:

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

Utilizza lo stesso comando per creare la nuova configurazione API che hai utilizzato per creare la configurazione API iniziale, come mostrato sopra in 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 su un gateway, la configurazione API potrebbe non essere eliminata finché il gateway non smette di utilizzarla.

Prima di eliminare una configurazione API in uso, devi:

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

Per saperne di più, consulta Eseguire il 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 in un gateway