Questa pagina è stata tradotta dall'API Cloud Translation.

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à man mano che svolgi il tutorial. Tutte le attività sono necessarie per eseguire il deployment di un gateway API per il servizio di backend Cloud Run.

Crea o seleziona un progetto Google Cloud.
Se non hai eseguito il deployment di un tuo servizio Cloud Run, esegui il deployment di un servizio di esempio. Consulta il passaggio 7 in Prima di iniziare.
Abilita i servizi API Gateway richiesti.
Crea una specifica OpenAPI che descriva la tua API e configura le route per il servizio di backend Cloud Run. Consulta la sezione Creare una configurazione API.
Esegui il deployment di un gateway API utilizzando la configurazione API. Consulta Eseguire il deployment di un gateway API.
Monitora l'attività nei tuoi servizi. Consulta Monitorare l'attività dell'API.
Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Pulizia.

Prima di iniziare

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 anziché selezionarne uno esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.
Verifica che la fatturazione sia attivata per il tuo progetto.
Attiva 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 la gcloud CLI
Aggiorna i componenti gcloud:
```
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 nella guida rapida Eseguire il 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, nonché della regione e dell'ID progetto in cui vengono eseguite le 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 non vedi i servizi richiesti nell'elenco, 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, consulta Servizi gcloud.

Creazione di una configurazione API

Prima che API Gateway possa essere utilizzato 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 specifica OpenAPI contenente annotazioni specializzate per definire il comportamento di API Gateway scelto. 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 questo nome file, ma puoi assegnarne un altro se preferisci.

Elenca ogni app nella sezione paths del file openapi2-run.yaml, come mostrato nell'esempio seguente:

# 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 dell'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 per coniare le chiavi API che consentono l'accesso a questa API. Consulta i requisiti per gli ID API per le linee guida per la 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 i tag di revisione per eseguire il versionamento 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 assume per impostazione predefinita il valore del campo address per l'affermazione sul segmento di pubblico JWT. Ciò può comportare un reclamo per il segmento di pubblico JWT imprevisto per Cloud Run se l'URL del tag di revisione viene utilizzato per address e non viene specificato 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à, questo comando la crea.
- 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 l'autenticazione configurata. Per ulteriori informazioni, vedi Creare un account di servizio.
  Nota: all'account di servizio utilizzato per creare una configurazione dell'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
```
Il completamento dell'operazione potrebbe richiedere diversi minuti, poiché la configurazione dell'API viene propagata ai sistemi a valle. La creazione di una configurazione API complessa potrebbe richiedere fino a dieci minuti.
Una volta creata la configurazione API, puoi visualizzarne i dettagli eseguendo questo comando:
```
gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID
```

Eseguire il deployment di un API Gateway

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 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
PROJECT_ID specifica il nome del tuo progetto Google Cloud.

Al termine, puoi utilizzare il seguente 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. Si tratta della parte del nome host dell'URL del gateway che utilizzerai per testare il deployment nel passaggio successivo.

Testare 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-a12bcd345e67f89g0h.uc.gateway.dev/hello

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

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

monitora l'attività dell'API

Visualizza i grafici delle attività per la tua API nella pagina API Gateway della console Google 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.
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 console Google Cloud.

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.