Creazione di 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, verifica di avere:

Requisiti per l'ID configurazione API

Molti dei comandi gcloud mostrati in questo tutorial 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.

Creazione di una configurazione API

Utilizza Google Cloud CLI per caricare la definizione dell'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, questo comando la crea.

Per creare una configurazione 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: esegui il deployment di un'API su API Gateway.

    Per saperne di più sulla creazione di una definizione e di una configurazione del servizio gRPC per la definizione dell'API, vedi 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 questo 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 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 maggiori dettagli, consulta Configurazione di un service account.

    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 dell'API viene propagata ai sistemi downstream. La creazione di una configurazione API complessa potrebbe richiedere fino a 10 minuti per essere completata correttamente. 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: 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'

  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.

Google Cloud CLI accetta molte opzioni, incluse 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 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)"

Configurazioni API di Listing

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 l'API e gli ID di configurazione per ottenere informazioni dettagliate sulla configurazione API:

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

Aggiornamento di una configurazione API

Non puoi modificare una configurazione API esistente, se non per aggiornarne le 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 \
  --update-labels=a=1,b=2

Utilizza il comando seguente 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

Passaggi successivi