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 specifica OpenAPI.

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

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

Requisiti per l'ID 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 configurazione API:

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

Crea una configurazione API

Crea una configurazione API caricando la definizione dell'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 server.url (OpenAPI 3.x) sia impostato su un'estensione x-google-endpoint nella configurazione API.

Per creare una configurazione API:

Console Google Cloud

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

Google Cloud CLI

Carica la definizione API per 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, questo comando la crea.

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

1. Passa alla directory contenente la definizione dell'API.

   Per saperne di più sulla creazione della specifica OpenAPI per la definizione dell'API, consulta Panoramica di OpenAPI e Guida rapida: proteggi il traffico verso un servizio con gcloud CLI.

   Per saperne di più sulla creazione di una definizione e di una configurazione del servizio gRPC per la definizione dell'API, consulta Configurare un servizio gRPC e Iniziare 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'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 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 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.
   • SERVICE_ACCOUNT_EMAIL specifica il account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata. Per saperne di più, consulta Configurare il account di servizio utilizzato per creare configurazioni API.

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

5. Al termine, puoi utilizzare questo comando 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: [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 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 nuovamente il comando.

gcloud CLI accetta molte opzioni, incluse quelle descritte nel 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 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 i gateway API di cui è stato eseguito il deployment nel tuo progetto Google Cloud .

Console Google Cloud

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

1. Nella console Google Cloud , 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 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, se non 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 dell'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 Creare una configurazione API.

Console Google Cloud

1. Nella console Google Cloud , 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 seguente comando 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 su un gateway, la configurazione API potrebbe non essere eliminata finché il gateway non la utilizza più.

Prima di eliminare una configurazione API in uso, devi:

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

Per saperne di più, consulta Eseguire il deployment di un'API in un gateway.

Console Google Cloud

1. Nella console Google Cloud , 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