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.
Per creare una configurazione API:
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.
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
Visualizza la guida per il comando
api-configs create
:gcloud api-gateway api-configs create --help
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.
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: 1111111@developer.gserviceaccount.com 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'
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.
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
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