Introduzione ad API Gateway e Cloud Run

Questa pagina mostra come configurare API Gateway per gestire e proteggere un servizio di backend Cloud Run.

Elenco attività

Utilizza il seguente elenco di attività mentre segui il tutorial. Tutte le attività sono necessarie per eseguire il deployment di un gateway API per il servizio di backend Cloud Run.

1. Crea o seleziona un Google Cloud progetto.
2. Se non hai eseguito il deployment di Cloud Run, esegui il deployment di un servizio di esempio. Vedi il passaggio 7 in Prima di iniziare.
3. Abilita i servizi API Gateway richiesti.
4. Crea una descrizione OpenAPI che descriva la tua API e configura le route al servizio di backend Cloud Run. Consulta Creazione di una configurazione API.
5. Esegui il deployment di un gateway API utilizzando la configurazione API. Consulta Deployment di un gateway API.
6. Monitorare l'attività sui tuoi servizi. Consulta Monitorare l'attività dell'API.
7. Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Prima di iniziare

1. Nella console Google Cloud , vai alla pagina Dashboard e seleziona o crea un progetto Google Cloud .

   Vai alla Dashboard

   Nota: se non prevedi di conservare le risorse che crei in questo tutorial, crea un nuovo progetto invece di selezionarne uno esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

2. Verifica che la fatturazione sia attivata per il tuo progetto.

   Abilita fatturazione

3. Prendi nota dell'ID progetto che vuoi utilizzare per questo tutorial. Nel resto di questa pagina, questo ID progetto viene indicato come PROJECT_ID.

4. Scarica e installa Google Cloud CLI.

   Scarica gcloud CLI

5. Aggiorna i gcloudcomponenti:

   gcloud components update

6. Imposta il progetto predefinito. Sostituisci PROJECT_ID con l' Google Cloud ID progetto.

   gcloud config set project PROJECT_ID

7. Se non hai eseguito il deployment del tuo servizio Cloud Run, segui i passaggi descritti nella Guida rapida: esegui il deployment di un container di esempio preimpostato per selezionare o creare un progetto e部署 un backend di esempio. Google Cloud Prendi nota dell'URL dell'app, nonché della regione e dell'ID progetto in cui sono state eseguite le tue app.

Attivare i servizi richiesti

API Gateway richiede l'abilitazione dei seguenti servizi Google:

Nome	Titolo
apigateway.googleapis.com	API API Gateway
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control

Utilizza i seguenti comandi per abilitare questi servizi:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Per saperne di più sui servizi gcloud, consulta Servizi gcloud.

Crea una configurazione API

Prima di poter utilizzare API Gateway per gestire il traffico verso il backend Cloud Run di cui hai eseguito il deployment, è necessaria una configurazione API.

Puoi creare una configurazione API utilizzando una descrizione OpenAPI che contiene annotazioni specializzate per definire il comportamento scelto di API Gateway. Devi aggiungere un campo specifico di Google che contenga l'URL di ogni app Cloud Run in modo che API Gateway disponga delle informazioni necessarie per richiamare un'app.

Per maggiori dettagli sulle estensioni OpenAPI supportate, vedi quanto segue:

• Estensioni OpenAPI 2.0 in API Gateway
• Estensioni OpenAPI 3.x in API Gateway

Per creare la configurazione API:

1. Crea un file di testo denominato openapi-run.yaml. Per praticità, questa pagina fa riferimento alla descrizione OpenAPI con questo nome file, ma puoi chiamarlo in un altro modo, se preferisci.
2. Copia i contenuti del seguente file nel file openapi-run.yaml:

   OpenAPI 2.0

   # openapi-run.yaml
   swagger: '2.0'
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Cloud Run backend
     version: 1.0.0
   schemes:
   - https
   produces:
   - application/json
   x-google-backend:
     address: APP_URL
   paths:
     /assets/{asset}:
       get:
         parameters:
           - in: path
             name: asset
             type: string
             required: true
             description: Name of the asset.
         summary: Assets
         operationId: getAsset
         responses:
           '200':
             description: A successful response
             schema:
               type: string
     /hello:
       get:
         summary: Cloud Run hello world
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   • Nel campo title, sostituisci API_ID con il nome della tua API e optional-string con una breve descrizione a tua scelta. Se la tua API non esiste ancora, il comando per creare la configurazione API creerà anche l'API con il nome che specifichi. Il valore del campo title viene utilizzato per creare chiavi API che concedono l'accesso a questa API. Consulta i requisiti per l'ID API per le linee guida sulla denominazione delle API.
   • Nel campo address della sezione x-google-backend, sostituisci APP_URL con l'URL effettivo del tuo servizio Cloud Run (il percorso completo dell'API chiamata). Ad esempio: https://hello-abc1def2gh-uc.a.run.app.
     Nota: se prevedi di utilizzare i tag di revisione per controllare le versioni del backend del servizio Cloud Run, devi specificare il campo jwt_audience in address nella sezione x-google-backend. Il valore del campo jwt_audience deve essere l'URL del servizio Cloud Run. Ad esempio:

     ...
       x-google-backend:
           address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
           jwt_audience: https://SERVICE_HOSTNAME
     ...

     Se il campo jwt_audience non è presente, l'estensione x-google-backend utilizza per impostazione predefinita il valore del campo address per l'attestazione del pubblico JWT. Ciò può comportare un'attestazione del pubblico JWT imprevista per Cloud Run se l'URL del tag di revisione viene utilizzato per address e non viene specificato alcun jwt_audience.

   OpenAPI 3.x

   # openapi-run.yaml
   openapi: 3.0.4
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Cloud Run backend
     version: 1.0.0
   # Define reusable components in x-google-api-management
   x-google-api-management:
     backends:
       cloudrun_backend:
         address: APP_URL
         deadline: 30.0
         pathTranslation: APPEND_PATH_TO_ADDRESS
         protocol: "http/1.1"
   # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
   x-google-backend: cloudrun_backend
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           "200":
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   • Nel campo title, sostituisci API_ID con il nome della tua API e optional-string con una breve descrizione a tua scelta. Se la tua API non esiste ancora, il comando per creare la configurazione API creerà anche l'API con il nome che specifichi. Il valore del campo title viene utilizzato per creare chiavi API che concedono l'accesso a questa API. Per le linee guida per la denominazione delle API, consulta Requisiti per l'ID API.
   • Nel campo address, sostituisci APP_URL con l'URL effettivo del tuo servizio Cloud Run (il percorso completo dell'API chiamata). Ad esempio https://hello-687541448612.us-central1.run.app.
   Nota: se prevedi di utilizzare i tag di revisione per controllare le versioni del backend del servizio Cloud Run, devi specificare il campo jwtAudience in address nella sezione x-google-api-management. Il valore del campo jwtAudience deve essere l'URL del servizio Cloud Run. Ad esempio:
   ...
     x-google-api-management:
       backends:
         cloudrun_backend:
           address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
           jwtAudience: https://SERVICE_HOSTNAME
   ...
   Se il campo jwtAudience non è presente, l'estensione x-google-backend corrisponde per impostazione predefinita al valore del campo address per l'attestazione del pubblico JWT. Ciò può comportare un'attestazione dell'audience JWT imprevista per Cloud Run se l'URL del tag di revisione viene utilizzato per address e non viene specificato alcun jwtAudience.
3. Inserisci il seguente comando, dove:
   • CONFIG_ID specifica il nome della configurazione API.
   • API_ID specifica il nome dell'API. Se l'API non esiste già, questo comando la crea.
   • PROJECT_ID specifica il nome del tuo progetto Google Cloud .
   • SERVICE_ACCOUNT_EMAIL specifica il account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata. Per saperne di più, vedi Creare un service account.
     Nota: il account di servizio utilizzato per creare una configurazione API per un backend Cloud Run deve avere il ruolo run.invoker assegnato.

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=openapi2-run.yaml \
     --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   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.

4. Una volta creata la configurazione API, puoi visualizzarne i dettagli eseguendo questo comando:

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

Esegui il deployment di un gateway API

Ora puoi eseguire il deployment dell'API su API Gateway. Il deployment di un'API su API Gateway definisce anche un URL esterno che i client API possono utilizzare per accedere all'API.

Esegui questo comando per eseguire il deployment della configurazione API appena creata in API 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 il nome del gateway.
• API_ID specifica il nome dell'API API Gateway associata a questo gateway.
• CONFIG_ID specifica il nome della configurazione API di cui è stato eseguito il deployment sul gateway.

• GCP_REGION è la regioneGoogle Cloud del gateway di cui è stato eseguito il deployment.

  Nota: i valori consentiti sono:

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

• PROJECT_ID specifica il nome del tuo progetto Google Cloud .

Al termine, puoi utilizzare questo comando per visualizzare i dettagli del gateway:

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

Prendi nota del valore della proprietà defaultHostname nell'output di questo comando. Questa è la parte del nome host dell'URL del gateway che utilizzerai per testare il deployment nel passaggio successivo.

Testa il deployment dell'API

Ora puoi inviare richieste all'API utilizzando l'URL generato al momento del deployment del gateway.

Inserisci il seguente URL nel browser web, dove:

• DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment.
• hello è il percorso specificato nella configurazione API.

https://DEFAULT_HOSTNAME/hello

Ad esempio:

https://my-gateway-687541448612.us-central1.run.app/hello

Dovresti vedere il container Cloud Run che esegue l'app nel browser.

Operazione riuscita. Il gateway gestisce l'accesso al servizio di backend Cloud Run.

Monitorare l'attività dell'API

1. Visualizza i grafici delle attività per la tua API nella pagina API Gateway della consoleGoogle Cloud . Fai clic sull'API per visualizzare i grafici delle attività nella pagina Panoramica. La visualizzazione dei dati relativi alle richieste nei grafici può richiedere alcuni minuti.

2. Esamina i log delle richieste per la tua API nella pagina Esplora log. Un link alla pagina Esplora log è disponibile nella pagina API Gateway della consoleGoogle Cloud .

   Una volta nella pagina API Gateway:

   1. Seleziona l'API da visualizzare.
   2. Fai clic sulla scheda Dettagli.
   3. Fai clic sul link nella sezione Log.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa guida rapida, puoi:

• Eliminare i gateway
• Eliminare l'API

In alternativa, puoi anche eliminare il progetto Google Cloud utilizzato per questo tutorial.