Configurare OpenAPI di Cloud Endpoints per Cloud Run con ESPv2

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, deploy del contenitore ESPv2 sullo stesso servizio Cloud Run.

1. 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.
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. 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 del tuo servizio di backend e gli eventuali requisiti di autenticazione. Devi anche aggiungere un campo specifico di Google contenente l'URL di ciascun servizio in modo che ESPv2 disponga delle informazioni necessarie per richiamare un servizio. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per saperne di più.

1. Crea un file di testo denominato openapi-run.yaml. Per comodità, questa pagina fa riferimento al documento OpenAPI con questo nome file, ma se preferisci puoi assegnargli un altro nome.
2. Il servizio di backend Cloud Run è definito nella parte superiore del file openapi-run.yaml, in una definizione x-google-backend. Ad esempio:

   swagger: '2.0'
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   host: CLOUD_RUN_HOSTNAME
   schemes:
     - https
   produces:
     - application/json
   x-google-backend:
     address: BACKEND_SERVICE_NAME
     protocol: h2
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         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.

3. Nel campo address della sezione x-google-backend, sostituisci BACKEND_SERVICE_NAME con l'URL effettivo del servizio Cloud Run di backend creato nel passaggio 6 della sezione Prima di iniziare.

   Questo esempio presuppone che tu stia utilizzando il servizio di backend hello creato nella guida rapida Esegui il deployment di un container di esempio preimpostato. Se utilizzi un altro servizio Cloud Run di backend, sostituisci BACKEND_SERVICE_NAME con l'URL del servizio Cloud Run.

4. 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 + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   host: gateway-12345-uc.a.run.app

5. Prendi nota del valore della proprietà title nel file openapi-run.yaml:

   title: Cloud Endpoints + Cloud Run

   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 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:

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

2. Carica la configurazione e crea un servizio gestito.

   gcloud endpoints services deploy openapi-run.yaml \
     --project ESP_PROJECT_ID

   Viene creato un nuovo servizio Endpoints con il nome specificato nel campo host del file openapi-run.yaml. Il servizio è 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-run.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

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.

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

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

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

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

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

2. 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 di Extensible Service Proxy 2.

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

Per ulteriori informazioni, consulta Che cosa sono i ruoli e le autorizzazioni?
4. Concedi all'autorizzazione ESPv2 l'autorizzazione per richiamare i tuoi servizi Cloud Run. Esegui il seguente comando per ogni servizio. Nel seguente comando:
   • Sostituisci BACKEND_SERVICE_NAME con il nome del servizio Cloud Run invocato. Se utilizzi il servizio di backend creato nella guida rapida Eseguire il deployment di un container di esempio predefinito, utilizza hello come valore.
   • 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 Compute predefinito, ovvero l'account di servizio utilizzato nel flag "member".

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

Per ulteriori informazioni, consulta Gestire l'accesso utilizzando 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 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 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

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

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