Deployment di un'API in un gateway

Prerequisiti

Prima di poter eseguire il deployment di una configurazione API in API Gateway, assicurati di avere:

Requisiti per l'ID gateway

Molti dei comandi gcloud mostrati di seguito richiedono di specificare l'ID del gateway nel formato GATEWAY_ID. API Gateway applica i seguenti requisiti per l'ID gateway:

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

Definizione dell'endpoint della configurazione API di cui è stato eseguito il deployment

Quando esegui il deployment di una configurazione API in un gateway, API Gateway crea un URL univoco per il gateway nel dominio gateway.dev. I client API utilizzeranno quindi un URL nel modulo riportato di seguito per accedere alla configurazione API di cui è stato eseguito il deployment:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

dove GATEWAY_ID è il nome del gateway, HASH è il codice hash univoco generato al momento del deployment dell'API e REGION_CODE è il codice per la regione Google Cloud in cui hai eseguito il deployment del gateway.

Ad esempio:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Esegui il deployment di una configurazione API in un gateway

Utilizza Google Cloud CLI per eseguire il deployment di una configurazione API su un gateway. Quando esegui il deployment della configurazione API, devi specificare il nome dell'API. Se il gateway non esiste già per l'API, viene creato anche da questo comando.

Per eseguire il deployment di una configurazione API in un gateway:

  1. Convalida l'ID progetto restituito dal comando seguente per assicurarti che il gateway 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

  2. Visualizza la guida per il comando gateway create:

    gcloud api-gateway gateways create --help

  3. Esegui questo comando per eseguire il deployment della configurazione API nel gateway:

    gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

    dove:

    • GATEWAY_ID specifica l'ID del nuovo gateway. Se il gateway non esiste già, questo comando lo crea.
    • API_ID specifica l'ID dell'API API Gateway associata al gateway.
    • CONFIG_ID specifica l'ID della configurazione API di cui è stato eseguito il deployment nel gateway. Quando crei un gateway, devi specificare una configurazione API.

    • GCP_REGION specifica la regione Google Cloud per il gateway di cui è stato eseguito il deployment.

    • PROJECT_ID specifica l'ID del progetto Google Cloud.

    Durante la creazione del gateway, gcloud restituisce informazioni al terminale.

  4. Una volta completato il gateway, puoi utilizzare il comando seguente per visualizzare i dettagli del gateway:

    gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

    Questo comando restituisce quanto segue:

    apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: GATEWAY_ID
name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
serviceAccount:
  email: gateway-111111@222222-tp.iam.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

    Prendi nota del valore della proprietà defaultHostname. Questa è la parte del nome host dell'URL del gateway. Per accedere a una configurazione API di cui è stato eseguito il deployment in questo gateway, utilizza un URL nel modulo:

    https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

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 un gateway:

  • --async: restituisci immediatamente il controllo al terminale, senza attendere il completamento dell'operazione.
  • --display-name=NAME: specifica il nome visualizzato del gateway, ovvero il nome mostrato nell'interfaccia utente. Non utilizzare spazi nel nome. Utilizza invece trattini e trattini bassi. Il valore predefinito è GATEWAY_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...: specifica le etichette associate al gateway.

Elenco dei gateway

Per elencare i gateway per un progetto specifico:

gcloud api-gateway gateways list --project=PROJECT_ID

Questo comando restituisce l'output nel formato:

GATEWAY_ID        LOCATION       DISPLAY_NAME     STATE     CREATE_TIME          UPDATE_TIME
my-gateway        us-central1    my-gateway       ACTIVE    2021-01-07T00:04:19  2022-05-21T00:33:46

Per elencare i gateway per un progetto e una regione specifici:

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Utilizza un'espressione filter per elencare i gateway associati a un'API specifica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

In alternativa, utilizza questo filter per elencare i gateway per una configurazione API specifica:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Utilizza gli ID progetto, regione e gateway per ottenere informazioni dettagliate sul gateway, inclusa l'identità della configurazione API di cui è stato eseguito il deployment nel gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Aggiornamento di un gateway

Aggiorna un gateway per:

  • Esegui il deployment di una configurazione API diversa nel gateway
  • Aggiorna il nome visualizzato
  • Aggiorna le etichette

Utilizza il seguente comando gcloud per aggiornare un gateway esistente, in cui UPDATE_OPTIONS viene sostituito con il flag e il valore di opzione del gateway che vuoi aggiornare: 

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID

Ad esempio, per aggiornare la configurazione API di cui è stato eseguito il deployment nel gateway:

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID

dove NEW_CONFIG_ID specifica la nuova configurazione API di cui eseguire il deployment nel gateway.

Per un elenco completo dei flag e degli argomenti di aggiornamento disponibili, consulta il riferimento gcloud api-gateway gateways update o utilizza il seguente comando per visualizzare tutte le opzioni di aggiornamento:

gcloud api-gateway gateways update --help

Eliminazione di un gateway

Utilizza il seguente comando gcloud per eliminare un gateway esistente:

gcloud api-gateway gateways delete GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Passaggi successivi