Configura Cloud Endpoints OpenAPI per le funzioni Cloud Run con ESPv2

Prenotare un nome host Cloud Run

Devi prenotare un nome host Cloud Run per il servizio ESPv2 per configurare la configurazione del servizio OpenAPI o gRPC. Per prenotare un nome host, devi eseguire il deployment di un container di esempio su Cloud Run. In un secondo momento, eseguirai il deployment del container ESPv2 sullo stesso servizio Cloud Run.

1. Assicurati che gcloud CLI sia autorizzata ad accedere ai tuoi dati e 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.
2. Imposta la regione.

   gcloud config set run/region us-central1

3. 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.

4. Prendi nota di CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. In un secondo momento, esegui il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME. Specifichi CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

Devi disporre di un documento OpenAPI basato sulla specifica OpenAPI v2.0 che descriva la superficie delle tue funzioni e qualsiasi requisito di autenticazione. Devi anche aggiungere un campo specifico di Google che contenga l'URL di ogni funzione in modo che ESPv2 disponga delle informazioni necessarie per richiamare una funzione. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per saperne di più.

1. Crea un file di testo denominato openapi-functions.yaml. Per comodità, questa pagina fa riferimento al documento OpenAPI con questo nome file, ma puoi assegnargli un altro nome, se preferisci.
2. Ogni funzione deve essere elencata nella sezione paths del file openapi-functions.yaml. 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

   Il rientro è importante per il formato YAML. Ad esempio, il campo host deve trovarsi allo stesso livello di info.
3. Nel campo address della sezione x-google-backend, sostituisci REGION con la regione Google Cloud in cui si trova la tua 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 suo 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 appropriato che specifichi l'host della funzione 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.

4. Nel campo host, specifica CLOUD_RUN_HOSTNAME, la porzione di nome host dell'URL riservato in precedenza in Riservare 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

5. 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.

6. Salva il documento OpenAPI.

Per informazioni sui campi del documento OpenAPI richiesti da Endpoints, vedi Configurazione di 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:

1. Assicurati di trovarti nella directory che contiene il documento OpenAPI.

2. 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 è configurato in base al documento OpenAPI.

   Durante la creazione e la configurazione del servizio, Service Management visualizza le informazioni nel 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 è composto da un timestamp seguito da un numero di revisione. Se esegui di nuovo il deployment di openapi-functions.yaml lo stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio e la cronologia dei deployment nella pagina Endpoints > Servizi della console Google Cloud .

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

Controllo dei servizi richiesti

Nella maggior parte dei casi, il comando gcloud endpoints services deploy attiva questi servizi richiesti. Tuttavia, il comando gcloud viene completato correttamente, ma non abilita 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 progettoGoogle Cloud esistente in cui questi servizi sono stati disattivati in modo esplicito.

Utilizza questo comando per verificare che i servizi richiesti siano abilitati:

gcloud services list

Se non vedi i servizi richiesti elencati, 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 il 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 viene visualizzato nella colonna Nome servizio.

• Per OpenAPI, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo host della specifica OpenAPI. Per gRPC, ENDPOINTS_SERVICE_NAME è ciò che hai specificato nel campo name della configurazione di gRPC Endpoints.

Per ulteriori informazioni sui comandi gcloud, consulta servizi gcloud.

Creazione di una nuova immagine ESPv2

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

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

1. Scarica questo script sul tuo computer locale in cui è installata gcloud CLI.

2. Esegui lo script con questo 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 prenotato 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

3. Lo script utilizza il comando gcloud per scaricare la configurazione del servizio, creare la configurazione del servizio in una nuova immagine ESPv2 e caricare la nuova immagine nel registro dei container del progetto. Lo script utilizza automaticamente l'ultima versione di ESPv2, indicata da 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"

Deployment del container ESPv2

1. 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 originariamente 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

2. Se vuoi configurare Endpoints per 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 di Extensible Service Proxy V2 beta.

3. Concedi all'ESPv2 l'autorizzazione a chiamare Service Management e Service Control.

• Nella console Google Cloud , vai alla pagina Cloud Run.

Vai alla pagina Cloud Run

• Puoi visualizzare l'istanza Cloud Run di cui hai eseguito il deployment e il account di servizio associato.
• Concedi le autorizzazioni necessarie al account di servizio:

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

Per ulteriori informazioni, consulta Che cosa sono ruoli e autorizzazioni?

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

   • Sostituisci FUNCTION_NAME con il nome della tua funzione e FUNCTION_REGION con la regione in cui è stato eseguito il deployment della funzione. Se utilizzi la funzione creata nella Guida rapida: 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 l'account di servizio Compute predefinito, 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 saperne di più, consulta Gestire l'accesso tramite IAM.

invia richieste all'API

Questa sezione mostra come inviare richieste all'API.

1. Crea una variabile di ambiente per il nome del servizio Endpoints. Si tratta del nome che hai 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"

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

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

Se non hai ricevuto una risposta riuscita, consulta Risoluzione dei problemi relativi agli errori di risposta.

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

monitora l'attività dell'API

1. Visualizza i grafici di attività per la tua API nella pagina Endpoints > Servizio nella console Google Cloud .

   Visualizzare i grafici delle attività di Endpoints

   La visualizzazione dei dati relativi alla richiesta nei grafici può richiedere alcuni minuti.

2. Esamina i log delle richieste per la tua API nella pagina Esplora log. Visualizzare i log delle richieste di Endpoints