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 esegui il tutorial. Tutte le attività sono necessarie per eseguire il deployment di API Gateway per il servizio di backend Cloud Run.

Crea o seleziona un progetto Google Cloud.
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.
Attiva i servizi API Gateway richiesti.
Crea una specifica OpenAPI che descriva l'API e configura le route per il tuo servizio di backend Cloud Run. Consulta la sezione Creazione di una configurazione API.
Esegui il deployment di un API Gateway utilizzando la configurazione API. Vedi Deployment di un API Gateway.
Monitora l'attività relativa ai tuoi servizi. Consulta Monitoraggio dell'attività dell'API.
Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Prima di iniziare

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

Nota: se non prevedi di conservare le risorse create in questo tutorial, crea un nuovo progetto anziché selezionarne uno esistente. Dopo aver completato questi passaggi, puoi eliminare il progetto, rimuovendo tutte le risorse associate.
Verifica che la fatturazione sia attivata per il tuo progetto.
Scopri come attivare la fatturazione
Prendi nota dell'ID progetto che vuoi utilizzare per questo tutorial. Nel resto di questa pagina, questo ID progetto è indicato come PROJECT_ID.
Scarica e installa Google Cloud CLI.
Scarica gcloud CLI
Aggiorna gcloudcomponenti:
```
gcloud components update
```
Imposta il progetto predefinito. Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud
```
gcloud config set project PROJECT_ID
```
Se non hai eseguito il deployment del tuo servizio Cloud Run, segui i passaggi descritti in Guida rapida: deployment di un container di esempio predefinito per selezionare o creare un progetto Google Cloud ed eseguire il deployment di un backend di esempio. Prendi nota dell'URL dell'app, della regione e dell'ID progetto in cui viene eseguito il deployment delle app.

Attivazione dei 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

Per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se i servizi richiesti non sono elencati, attivali:

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

Per ulteriori informazioni sui servizi gcloud, vedi Servizi gcloud.

Creazione di una configurazione API

Prima di poter essere utilizzato per gestire il traffico verso il backend Cloud Run di cui hai eseguito il deployment, API Gateway deve avere una configurazione API.

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

Crea un file di testo denominato openapi2-run.yaml. Per praticità, questa pagina fa riferimento alla specifica OpenAPI con il nome di file, ma puoi nominarla con un altro nome, se preferisci.

Elenca tutte le tue app nella sezione paths del file openapi2-run.yaml, come mostrato di seguito:

# openapi2-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 l'API non esiste già, il comando per creare la configurazione API creerà anche l'API con il nome specificato. Il valore del campo title viene utilizzato durante il mining di chiavi API che concedono l'accesso a questa API. Consulta i requisiti relativi agli ID API per le linee guida relative alla denominazione delle API.
Nel campo address della sezione x-google-backend, sostituisci APP_URL con l'URL effettivo del servizio Cloud Run (il percorso completo dell'API chiamata). Ad esempio: https://hello-abc1def2gh-uc.a.run.app.
Nota: se prevedi di utilizzare tag di revisione per eseguire la versione 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, per impostazione predefinita l'estensione x-google-backend utilizzerà il valore del campo address per la rivendicazione del segmento di pubblico JWT. Ciò può comportare una rivendicazione imprevista del segmento di pubblico JWT per Cloud Run se per address viene utilizzato l'URL del tag di revisione e non viene specificato alcun elemento jwt_audience.
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à, viene creata da questo comando.
- PROJECT_ID specifica il nome del tuo progetto Google Cloud.
- SERVICE_ACCOUNT_EMAIL specifica l'account di servizio utilizzato per firmare i token per i backend con autenticazione configurata. Per saperne di più, vedi Creare un account di servizio.
  Nota: all'account di servizio utilizzato per creare una configurazione API per un backend Cloud Run deve essere assegnato il ruolo run.invoker.
```
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
```
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.
Dopo aver creato la configurazione API, puoi visualizzarne i dettagli eseguendo questo comando:
```
gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID
```

Deployment di un API Gateway

Ora puoi eseguire il deployment della tua 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 al gateway.
CONFIG_ID specifica il nome della configurazione API di cui è stato eseguito il deployment nel gateway.
GCP_REGION è la regione Google Cloud per il 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
Il supporto per i gateway API Gateway creati in precedenza in asia-east1 terminerà il 1° novembre 2022. Devi esaminare tutti i gateway attualmente in esecuzione in asia-east1 ed eliminarli o ricrearli in una nuova località in base alle esigenze.
PROJECT_ID specifica il nome del tuo progetto Google Cloud.

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

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.

Test del deployment dell'API

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

Inserisci il seguente URL nel tuo 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-a12bcd345e67f89g0h.uc.gateway.dev/hello

Dovresti vedere il container Cloud Run che esegue la tua app nel browser.

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

Monitora l'attività dell'API

Visualizza i grafici dell'attività per la tua API nella pagina API Gateway nella console Google Cloud. Fai clic sull'API per visualizzare i grafici delle attività nella pagina Panoramica. Potrebbero essere necessari alcuni istanti prima che le richieste risultino nei grafici.
Esamina i log delle richieste per l'API nella pagina Esplora log. Un link alla pagina Esplora log è disponibile nella pagina Gateway API della console Google Cloud.
Vai alla pagina API Gateway
Nella pagina API Gateway:
1. Seleziona l'API da visualizzare.
2. Fai clic sulla scheda Dettagli.
3. Fai clic sul link in Log.

Esegui la pulizia

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

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