Crea una configurazione API

Questa pagina descrive come creare una configurazione API da eseguire il deployment su API Gateway.

Prima di iniziare

Prima di creare una configurazione API:

• Prepara l'ambiente di sviluppo come descritto in Configurare l'ambiente di sviluppo.

• Crea una definizione API come una specifica OpenAPI.

• Se utilizzi Google Cloud CLI, crea facoltativamente un'API. Se l'API non esiste, la creazione della configurazione API la crea.

  Nota: quando utilizzi la Google Cloud console, l'API e la configurazione API vengono create durante il deployment dell'API in un gateway.

Requisiti per l'ID di configurazione API

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

• La 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.

Crea una configurazione API

Crea una configurazione API caricando la definizione API.

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 servizi gRPC per i servizi gRPC su Cloud Run.

Se managedService nella definizione API è impostato su un servizio ESPv2 Beta, assicurati che il campo host (OpenAPI 2.0) o il campo server.url (OpenAPI 3.x) sia impostato su un'estensione x-google-endpoint nella configurazione API.

Se la definizione API configura le quote, assicurati che le metriche e i limiti delle quote rimangano coerenti in tutte le configurazioni API attive prima di crearne una nuova. API Gateway le applica all'intera API anziché a una singola configurazione API, quindi qualsiasi metrica o limite dichiarato da una nuova configurazione API sostituisce la definizione per l'intera API. Se rinomini o rimuovi una metrica, i gateway che pubblicano ancora una configurazione API precedente restituiscono errori per i metodi con applicazione delle quote. Per ulteriori informazioni, consulta Le quote si applicano all'intera API.

Per creare una configurazione API:

Google Cloud Console

Crea una configurazione API quando esegui il deployment di un'API in un gateway.

Google Cloud CLI

Carica la definizione API per creare una configurazione API. Quando carichi la definizione API, devi specificare il nome dell'API. Se l'API non esiste già in API Gateway, questo comando la crea.

Nota: se vuoi utilizzare OpenAPI 3.x, assicurati di aggiornare i componenti gcloud CLI prima di creare una configurazione API per evitare errori durante il caricamento della definizione API.

1. Passa alla directory contenente la definizione API.

   Per ulteriori informazioni sulla creazione della specifica OpenAPI per la definizione API, consulta Panoramica di OpenAPI e Guida rapida: proteggere il traffico verso un servizio con gcloud CLI.

   Per ulteriori informazioni sulla creazione di una definizione e una configurazione del servizio gRPC per la definizione API, consulta Configurare un servizio gRPC e Inizia a utilizzare 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 comando seguente e sostituisci PROJECT_ID con l' Google Cloud ID progetto 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 API.
   • SERVICE_ACCOUNT_EMAIL specifica il account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata. Per ulteriori dettagli, consulta Configurare il account di servizio utilizzato per creare le configurazioni API.

   Durante la creazione dell'API e della configurazione API, API Gateway restituisce informazioni al terminale. Il completamento di questa operazione potrebbe richiedere diversi minuti, poiché la configurazione API viene propagata ai sistemi downstream. La 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. Al termine, puoi utilizzare il comando seguente per visualizzare i dettagli della nuova configurazione API:

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

   Questo comando restituisce quanto segue:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
         backendConfig:
           googleServiceAccount: 1111111@
   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 Servizio gestito 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 di nuovo il comando.

gcloud CLI accetta molte opzioni, incluse quelle descritte nella documentazione di riferimento di Google Cloud CLI. 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 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 \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

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

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

Elenca le configurazioni API

Elenca tutti gli API Gateway di cui è stato eseguito il deployment nel tuo Google Cloud progetto.

Google Cloud Console

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

1. Nella Google Cloud console, vai alla pagina API Gateway.

   Vai ad API Gateway

2. Fai clic sull'API richiesta.
3. Fai clic sulla scheda Configurazioni.

Nella pagina viene visualizzato l'elenco delle configurazioni API disponibili.

Google Cloud CLI

Per elencare le configurazioni API per un progetto specifico:

gcloud api-gateway api-configs list 

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 

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

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

Aggiorna una configurazione API

Non puoi modificare una configurazione API esistente, tranne per aggiornarne le 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 API.
2. Carica la definizione 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 in Crea una configurazione API.

Google Cloud Console

1. Nella Google Cloud console, vai alla pagina API Gateway.

   Vai ad API Gateway

2. Fai clic sull'API richiesta.
3. Fai clic sulla scheda Configurazioni.
4. Fai clic sulla configurazione API richiesta.
5. Fai clic su modifica Modifica.
6. Modifica Nome visualizzato o Etichette.
7. Fai clic su Salva.

Google Cloud CLI

Utilizza il seguente comando `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 \
  --update-labels=a=1,b=2

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

gcloud api-gateway api-configs update --help

Elimina una configurazione API

Avviso: se hai eseguito il deployment della configurazione API in un gateway, la configurazione API potrebbe non essere 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 saperne di più, consulta Esegui il deployment di un'API in un gateway.

Google Cloud Console

1. Nella Google Cloud console, vai alla pagina API Gateway.

   Vai ad API Gateway

2. Fai clic sull'API richiesta.
3. Fai clic sulla scheda Configurazioni.
4. Fai clic su Altro e poi su Elimina per eliminare la configurazione API scelta.

Google Cloud CLI

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

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

Passaggi successivi

• Esegui il deployment di un'API in un gateway