Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare OpenAPI di Cloud Endpoints per le funzioni Cloud Run con ESPv2

Questa pagina mostra come configurare Cloud Endpoints su funzioni Cloud Run. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per le funzioni Cloud Run, esegui il deployment del container ESPv2 precompilato in Cloud Run. Poi proteggi le funzioni utilizzando IAM di Cloud Run Functions in modo che ESPv2 possa richiamarle.

Con questa configurazione, ESPv2 intercetta tutte le richieste alle tue funzioni ed esegue tutti i controlli necessari (ad esempio l'autenticazione) prima di invocare la funzione. Quando la funzione risponde, ESPv2 raccoglie e registra la telemetria, come mostrato nella figura seguente. Puoi visualizzare le metriche della funzione nella pagina Endpoints > Servizi nella console Google Cloud.

Architettura di Endpoints

Per una panoramica di Cloud Endpoints, consulta Informazioni su Endpoints e Architettura di Endpoints.

Migrazione a ESPv2

Le versioni precedenti di Cloud Endpoints supportavano l'utilizzo di Extensible Service Proxy (ESP) con Cloud Functions. Se hai API esistenti di cui vuoi eseguire la migrazione a ESPv2, consulta Eseguire la migrazione a Extensible Service Proxy 2 per saperne di più.

Elenco attività

Utilizza il seguente elenco di attività man mano che svolgi il tutorial. Tutte le attività sono obbligatorie per completare questo tutorial.

Crea un progetto Google Cloud e, se non hai eseguito il deployment delle tue funzioni Cloud Run, esegui il deployment di una funzione di backend di esempio. Vedi Prima di iniziare.
Riserva un nome host Cloud Run per il servizio ESPv2. Consulta Prenotare un nome host Cloud Run.
Crea un documento OpenAPI che descriva la tua API e configura le route alle tue funzioni Cloud Run. Consulta Configurare Endpoints.
Esegui il deployment del documento OpenAPI per creare un servizio gestito. Consulta Eseguire il deployment della configurazione di Endpoints.
Crea una nuova immagine Docker ESPv2 con la configurazione del servizio Endpoints. Consulta la sezione Creare una nuova immagine ESPv2.
Esegui il deployment del container ESPv2 su Cloud Run. Quindi, concedi a ESPv2 l'autorizzazione IAM (Identity and Access Management) per richiamare il servizio. Consulta Eseguire il deployment del contenitore ESPv2.
Richiama una funzione. Consulta Invio di una richiesta all'API.
Monitora l'attività nelle tue funzioni. Consulta Monitorare l'attività dell'API.
Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Pulizia.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.

Prima di iniziare

Prima di utilizzare Endpoints per le funzioni Cloud Run, ti consigliamo di:

Crea un nuovo progetto Google Cloud da utilizzare per il deployment del contenuto ESPv2 in Cloud Run.
Crea un nuovo progetto o selezionane uno esistente per le funzioni Cloud Run.

Per la configurazione:

Nella console Google Cloud, vai alla pagina Gestisci risorse e crea un progetto.
Vai alla pagina Gestisci risorse
Verifica che la fatturazione sia attivata per il tuo progetto.
Scopri come attivare la fatturazione
Prendi nota dell'ID progetto, perché ti servirà in seguito. Nel resto di questa pagina, questo ID progetto è indicato come ESP_PROJECT_ID.
Prendi nota del numero del progetto perché ti servirà in seguito. Nel resto di questa pagina, questo numero di progetto è indicato come ESP_PROJECT_NUMBER.
Scarica e installa Google Cloud CLI.
Scarica la gcloud CLI
Se non hai eseguito il deployment delle tue funzioni Cloud Run di backend, segui i passaggi descritti in Guida rapida: utilizzo di Google Cloud CLI per selezionare o creare un progetto Google Cloud ed eseguire il deployment di una funzione di esempio. Prendi nota della regione e dell'ID progetto in cui vengono eseguite le funzioni. Nel resto di questa pagina, questo ID progetto è indicato come FUNCTIONS_PROJECT_ID.

Prenotazione di un nome host Cloud Run

Per configurare il documento OpenAPI o la configurazione del servizio gRPC, devi prenotare un nome host Cloud Run per il servizio ESPv2. Per prenotare un nome host, esegui il deployment di un container di esempio in Cloud Run. Successivamente, eseguirai il deployment del contenitore ESPv2 sullo stesso servizio Cloud Run.

Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e ai tuoi servizi.
1. Accedi.
```
gcloud auth login
```
2. Nella nuova scheda del browser che si apre, scegli un account con il ruolo Editor o Proprietario nel progetto Google Cloud che hai creato per il deployment di ESPv2 in Cloud Run.

Imposta la regione.

gcloud config set run/region us-central1

Esegui il deployment dell'immagine di esempio gcr.io/cloudrun/hello in Cloud Run. Sostituisci CLOUD_RUN_SERVICE_NAME con il nome che vuoi utilizzare per il servizio.

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESP_PROJECT_ID

Al termine, il comando visualizza un messaggio simile al seguente:

Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Ad esempio, se imposti CLOUD_RUN_SERVICE_NAME su gateway:

Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

In questo esempio, https://gateway-12345-uc.a.run.app è il CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app è il CLOUD_RUN_HOSTNAME.

Prendi nota di CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. Successivamente, esegui il deployment di ESPv2 nel servizio CLOUD_RUN_SERVICE_NAME Cloud Run. Specifica CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

Devi disporre di un documento OpenAPI basato sulla specifica OpenAPI 2.0 che descriva l'interfaccia delle tue funzioni e gli eventuali requisiti di autenticazione. Devi anche aggiungere un campo specifico di Google contenente l'URL di ogni funzione in modo che ESPv2 disponga delle informazioni necessarie per invocare una funzione. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per saperne di più.

Crea un file di testo denominato openapi-functions.yaml. Per comodità, questa pagina fa riferimento al documento OpenAPI con questo nome file, ma se preferisci puoi assegnargli un altro nome.

Ogni funzione deve essere elencata nella sezione paths del openapi-functions.yaml file. Ad esempio:

swagger: '2.0'
info:
  title: Cloud Endpoints + GCF
  description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
  version: 1.0.0
host: HOST
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
        protocol: h2
      responses:
        '200':
          description: A successful response
          schema:
            type: string

L'indentazione è importante per il formato YAML. Ad esempio, il campo host deve trovarsi allo stesso livello di info.

Nel campo address della sezione x-google-backend, sostituisci REGION con la regione Google Cloud in cui si trova la funzione, FUNCTIONS_PROJECT_ID con l'ID progetto Google Cloud e FUNCTIONS_NAME con il nome della funzione. Ad esempio:
```
x-google-backend:
  address: https://us-central1-myproject.cloudfunctions.net/helloGET
```
Se vuoi proteggere la tua funzione Cloud Run consentendo solo a ESPv2 di richiamarla, assicurati che il campo address includa il nome della funzione se jwt_audience non è specificato. Ad esempio:
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: CONSTANT_ADDRESS
```
Se viene specificato jwt_audience, il relativo valore deve includere anche il nome della funzione. Ad esempio:
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
  jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: APPEND_PATH_TO_ADDRESS
```
ESPv2 genera un token ID quando chiama la funzione Cloud Run per l'autenticazione. Il token ID deve avere un audience corretto che specifichi l'host e il nome della funzione. ESPv2 imposta audience per il token ID utilizzando il valore nel campo jwt_audience se specificato, altrimenti utilizza il campo address.
Nel campo host, specifica CLOUD_RUN_HOSTNAME, la parte del nome host dell'URL che è stata prenotata sopra in Prenotazione di un nome host Cloud Run. Non includere l'identificatore di protocollo, https://. Ad esempio:
```
swagger: '2.0'
  info:
    title: Cloud Endpoints + GCF
    description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
    version: 1.0.0
  host: gateway-12345-uc.a.run.app
```
Prendi nota del valore della proprietà title nel file openapi-functions.yaml:
```
title: Cloud Endpoints + GCF
```
Il valore della proprietà title diventa il nome del servizio Endpoints dopo il deployment della configurazione.
Salva il documento OpenAPI.

Per informazioni sui campi nel documento OpenAPI richiesti da Endpoints, consulta Configurare Endpoints.

esegui il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione di Endpoints, utilizza il comando gcloud endpoints services deploy. Questo comando utilizza Service Management per creare un servizio gestito.

Per eseguire il deployment della configurazione di Endpoints:

Assicurati di essere nella directory che contiene il documento OpenAPI.
Carica la configurazione e crea un servizio gestito.
```
gcloud endpoints services deploy openapi-functions.yaml \
    --project ESP_PROJECT_ID
```
Viene creato un nuovo servizio Endpoints con il nome specificato nel campo host del file openapi-functions.yaml. Il servizio viene configurato in base al documento OpenAPI.

Durante la creazione e la configurazione del servizio, Service Management visualizza informazioni sul terminale. Al termine del deployment, viene visualizzato un messaggio simile al seguente:
```
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
```
CONFIG_ID è l'ID univoco della configurazione del servizio Endpoints creato dal deployment. Ad esempio:
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
L'ID configurazione del servizio è costituito da un timestamp seguito da un numero di revisione. Se esegui di nuovo il deployment di openapi-functions.yaml nello stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio e la cronologia di implementazione nella pagina Endpoints > Servizi della console Google Cloud.

Se viene visualizzato un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.

Verifica dei servizi richiesti

Come minimo, Endpoints ed ESP richiedono l'attivazione dei seguenti servizi Google:

Nome	Titolo
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

Nella maggior parte dei casi, il comando gcloud endpoints services deploy attiva questi servizi obbligatori. Tuttavia, il comando gcloud viene completato correttamente, ma non attiva i servizi richiesti nelle seguenti circostanze:

Se hai utilizzato un'applicazione di terze parti come Terraform e non includi questi servizi.
Hai eseguito il deployment della configurazione di Endpoints in un progetto Google Cloud esistente in cui questi servizi sono stati disattivati esplicitamente.

Utilizza il seguente comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti nell'elenco, attivali:

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

Abilita anche il servizio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Per determinare ENDPOINTS_SERVICE_NAME, puoi:

Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoints nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è riportato nella colonna Nome servizio.
Per OpenAPI, ENDPOINTS_SERVICE_NAME è il valore specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è il valore specificato nel campo name della configurazione degli endpoint gRPC.

Per ulteriori informazioni sui comandi gcloud, consulta Servizi gcloud.

Creazione di una nuova immagine ESPv2

Crea la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. In un secondo momento, eseguirai il deployment di questa immagine sul servizio Cloud Run riservato.

Nota:

Questo passaggio è obbligatorio.

La configurazione del servizio deve essere integrata in una nuova immagine Docker perché Cloud Run è un servizio scalabile fino a zero. Ciò significa che, in assenza di traffico, tutte le istanze vengono eliminate. Quando il traffico aumenta, vengono create nuove istanze on demand. Questo tipo di creazione di istanze di servizio è chiamato anche avvio a freddo. Per saperne di più, consulta la documentazione sulla concorrenza di Cloud Run.

Se l'immagine Docker non avesse la configurazione del servizio integrata, Cloud Run dovrebbe effettuare due chiamate API a Google ServiceManagement all'avvio a freddo. Queste chiamate vengono conteggiate nella quota dell'API Google ServiceManagement.

Se esegui la compilazione della configurazione del servizio nell'immagine Docker ESPv2, rimuovi le due chiamate API ed eviti di influire sul conteggio delle quote per il servizio Google ServiceManagement. Questo passaggio velocizza anche la creazione della nuova istanza di servizio e riduce la latenza per le richieste in attesa della nuova istanza.

Devi eseguire di nuovo l'intero passaggio e rieseguire il deployment del nuovo contenitore:

Ogni volta che modifichi ed esegui nuovamente il deployment della configurazione del servizio Endpoints. In caso contrario, le modifiche alla configurazione del servizio non verranno propagate a ESPv2.
Quando viene rilasciata una nuova versione di ESPv2. In caso contrario, la versione precedente di ESPv2 rimarrà di cui è stato eseguito il deployment.

Per compilare la configurazione del servizio in una nuova immagine Docker ESPv2:

Scarica questo script sulla tua macchina locale su cui è installata gcloud CLI.

Nota:
Questo script richiede bash. Se non utilizzi macOS/Linux, puoi eseguirlo su Cloud Shell, Compute Engine o Windows Subsystem for Linux.

Esegui lo script con il seguente comando:

chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID

Per CLOUD_RUN_HOSTNAME, specifica il nome host dell'URL che hai riservato sopra in Prenotazione di un nome host Cloud Run. Non includere l'identificatore di protocollo, https://.

Ad esempio:

chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id

Lo script utilizza il comando gcloud per scaricare la configurazione del servizio, compilarla in una nuova immagine ESPv2 e caricarla nel registry dei container del progetto. Lo script utilizza automaticamente la versione più recente di ESPv2, indicata dal carattere ESP_VERSION nel nome dell'immagine di output. L'immagine di output viene caricata in:
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Ad esempio:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Nota:
Passa il flag -z allo script per generare l'immagine in un'altra posizione del registry.

Ad esempio, per inviare l'immagine ESPv2 generata a un data center dell'Unione Europea, passa -z eu allo script.

Deployment del container ESPv2

Esegui il deployment del servizio Cloud Run ESPv2 con la nuova immagine creata sopra. Sostituisci CLOUD_RUN_SERVICE_NAME con lo stesso nome del servizio Cloud Run che hai utilizzato quando hai prenotato inizialmente il nome host sopra in Prenotazione di un nome host Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
Nota:
Se vuoi che ESPv2 gestisca l'accesso, utilizza il flag --allow-unauthenticated per assicurarti che ESPv2 verifichi il token JWT. Se il flag non viene utilizzato, il token JWT viene intercettato e verificato da Cloud Run <a=" docs="" managing-access"="" run="" securing="">access control IAM server. Poiché IAM ed ESPv2 utilizzano la stessa riga di intestazione Authorization, non funzionano insieme. Assicurati di utilizzarne solo uno. Ti consigliamo di utilizzare IAM anziché ESPv2 per gestire l'accesso.</a=">
Se vuoi configurare Endpoints in modo da utilizzare opzioni di avvio di ESPv2 aggiuntive, ad esempio l'attivazione di CORS, puoi passare gli argomenti nella variabile di ambiente ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID
```
Per ulteriori informazioni ed esempi sull'impostazione della variabile di ambiente ESPv2_ARGS, incluso l'elenco delle opzioni disponibili e informazioni su come specificare più opzioni, consulta Flag beta di Extensible Service Proxy 2.
Concedi a ESPv2 l'autorizzazione per chiamare Gestione servizi e Controllo di servizio.

Nella console Google Cloud, vai alla pagina Cloud Run.

Vai alla pagina Cloud Run

Puoi vedere l'istanza Cloud Run di cui hai eseguito il deployment e l'account di servizio associato.
Concedi le autorizzazioni richieste all'account di servizio:

gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/servicemanagement.serviceController

Che cosa sono i ruoli e le autorizzazioni?

Concedi a ESPv2 l'autorizzazione a richiamare le tue funzioni. Esegui il seguente comando per ogni funzione. Nel seguente comando:

Nota:
Questo passaggio non è necessario se il servizio Cloud Run ESPv2 viene disegnato senza utilizzare il flag --service-account e il servizio di backend BACKEND_SERVICE_NAME viene disegnato nel progetto ESP_PROJECT_NUMBER.
- Sostituisci FUNCTION_NAME con il nome della funzione e FUNCTION_REGION con la regione in cui è eseguita il deployment della funzione. Se utilizzi la funzione creata nella guida rapida all'utilizzo di Google Cloud CLI, utilizza helloGET come nome.
- Sostituisci ESP_PROJECT_NUMBER con il numero del progetto che hai creato per ESPv2. Un modo per trovarlo è andare alla pagina IAM nella console Google Cloud e trovare il service account predefinito di Compute Engine, ovvero l'account di servizio utilizzato nel flag member.
```
gcloud functions add-iam-policy-binding FUNCTION_NAME \
   --region FUNCTION_REGION \
   --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role "roles/cloudfunctions.invoker" \
   --project FUNCTIONS_PROJECT_ID
```

Per ulteriori informazioni, consulta Gestire l'accesso tramite IAM.

invia richieste all'API

Questa sezione mostra come inviare richieste all'API.

Crea una variabile di ambiente per il nome del servizio Endpoints. Si tratta del nome specificato nel campo host del tuo documento OpenAPI. Ad esempio:
- Linux o macOS:
  
  export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
- Windows PowerShell:
  
  $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux o Mac OS

Utilizza curl per inviare una richiesta HTTP utilizzando la variabile di ambiente ENDPOINTS_HOST impostata nel passaggio precedente.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

PowerShell

Utilizza Invoke-WebRequest per inviare una richiesta HTTP utilizzando la variabile di ambiente ENDPOINTS_HOST impostata nel passaggio precedente.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

Nell'esempio precedente, le prime due righe terminano con un backtick. Quando incolli l'esempio in PowerShell, assicurati che non ci sia uno spazio dopo i backtick. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, consulta Invoke-WebRequest nella documentazione di Microsoft.

App di terze parti

Puoi utilizzare un'applicazione di terze parti, ad esempio l'estensione del browser Chrome Postman.

Seleziona GET come verbo HTTP.
Per l'intestazione, seleziona la chiave content-type e il valore application/json.
Utilizza l'URL effettivo anziché la variabile di ambiente, ad esempio:
```
https://gateway-12345-uc.a.run.app/hello
```

Se non hai ricevuto una risposta positiva, consulta Risoluzione dei problemi relativi alle risposte.

Hai eseguito il deployment e il test di un'API in Endpoints.

monitora l'attività dell'API

Visualizza i grafici delle attività della tua API nella pagina Endpoints > Servizio nella console Google Cloud.

Visualizzare i grafici delle attività di Endpoints

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. Visualizzare i log delle richieste di Endpoints

Creazione di un portale per gli sviluppatori per l'API

Puoi utilizzare il portale Cloud Endpoints per creare un portale per gli sviluppatori, un sito web che puoi utilizzare per interagire con l'API di esempio. Per saperne di più, consulta la panoramica del portale Cloud Endpoints.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa pagina, segui questi passaggi.

Consulta la sezione Eliminare un'API e le relative istanze per informazioni su come interrompere i servizi utilizzati da questo tutorial.