Configura Cloud Endpoints OpenAPI for Cloud Functions con ESPv2
Questa pagina mostra come configurare Cloud Endpoints su Cloud Functions. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per Cloud Functions, esegui il deployment del container ESPv2 predefinito in Cloud Run. Proteggi quindi le tue funzioni utilizzando Cloud Functions IAM in modo che ESPv2 possa richiamarle.
Una volta configurata, ESPv2 intercetta tutte le richieste alle tue funzioni ed esegue tutti i controlli necessari, ad esempio l'autenticazione, prima di richiamare la funzione. Quando la funzione risponde, ESPv2 raccoglie e segnala la telemetria, come mostrato nella figura seguente. Puoi visualizzare le metriche per la funzione nella pagina Endpoint > Servizi nella console Google Cloud.
Per una panoramica di Cloud Endpoints, consulta Informazioni sugli endpoint e sull'architettura degli endpoint.
Migrazione a ESPv2
Le versioni precedenti di Cloud Endpoints supportavano l'utilizzo di Extensible Service Proxy (ESP) con Cloud Functions. Se disponi di API esistenti di cui vuoi eseguire la migrazione a ESPv2, consulta Eseguire la migrazione a Extensible Service Proxy V2 per saperne di più.
Elenco attività
Utilizza il seguente elenco di attività mentre esegui il tutorial. Per completare questo tutorial sono necessarie tutte le attività.
- Crea un progetto Google Cloud e, se non hai eseguito il deployment delle tue funzioni Cloud Functions, esegui il deployment di una funzione di backend di esempio. Vedi Prima di iniziare.
- Prenota un nome host di Cloud Run per il servizio ESPv2. Vedi Prenotare un nome host di Cloud Run.
- Crea un documento OpenAPI che descriva la tua API e configura le route per le tue funzioni Cloud Functions. Vedi Configurazione di Endpoints.
- Esegui il deployment del documento OpenAPI per creare un servizio gestito. Vedi Deployment della configurazione di Endpoints.
- Crea una nuova immagine Docker ESPv2 con la configurazione del servizio Endpoints. Consulta la sezione Creazione di una nuova immagine ESPv2.
- Eseguire il deployment del container ESPv2 in Cloud Run. Concedi quindi a ESPv2 l'autorizzazione Identity and Access Management (IAM) per richiamare il servizio. Vedi Deployment del container ESPv2.
- Richiamare una funzione. Vedi Invio di una richiesta all'API.
- Monitora l'attività relativa alle tue funzioni. Consulta Monitoraggio dell'attività dell'API.
- Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.
Costi
In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:
Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.
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 Cloud Functions, ti consigliamo di:
Crea un nuovo progetto Google Cloud da utilizzare quando esegui il deployment del container ESPv2 in Cloud Run.
Crea un nuovo progetto o selezionane uno esistente per le tue funzioni Cloud Functions.
Per effettuare la configurazione:
Nella console Google Cloud, vai alla pagina Gestisci risorse e crea un progetto.
Verifica che la fatturazione sia attivata per il tuo progetto.
Prendi nota dell'ID progetto perché ti servirà in un secondo momento. Nel resto di questa pagina, questo ID progetto è indicato come ESP_PROJECT_ID.
Prendi nota del numero di progetto perché è necessario in seguito. Nel resto di questa pagina, questo numero di progetto è indicato come ESP_PROJECT_NUMBER.
Scarica e installa Google Cloud CLI.
Se non hai eseguito il deployment delle tue funzioni Cloud Functions di backend, segui i passaggi descritti in Guida rapida all'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 viene eseguito il deployment delle funzioni. Nel resto di questa pagina, questo ID progetto è indicato come FUNCTIONS_PROJECT_ID.
Prenotazione di un nome host di Cloud Run
Devi prenotare un nome host Cloud Run per il servizio ESPv2 per configure la configurazione del documento OpenAPI o del servizio gRPC. Per prenotare un nome host, eseguirai il deployment di un container di esempio in Cloud Run. In un secondo momento, deploy del container ESPv2 sullo stesso servizio Cloud Run.
-
Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati e servizi.
- Accedi.
gcloud auth login
- 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 eseguire il deployment di ESPv2 in Cloud Run.
- Accedi.
-
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
Una volta completato correttamente, 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
è CLOUD_RUN_SERVICE_URL egateway-12345-uc.a.run.app
è CLOUD_RUN_HOSTNAME. - Annota CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME.
In seguito eseguirai il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME.
CLOUD_RUN_HOSTNAME specifichi 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 ed eventuali requisiti di autenticazione. Devi anche aggiungere un campo specifico di Google contenente l'URL di ogni funzione, in modo che l'ESPv2 disponga delle informazioni necessarie per richiamare una funzione. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per ulteriori informazioni.
-
Crea un file di testo denominato
openapi-functions.yaml
. Per praticità, questa pagina fa riferimento al documento OpenAPI con quel nome di file, ma puoi nominarlo con un altro nome, se preferisci. -
Ogni funzione deve essere elencata nella sezione
paths
del fileopenapi-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 campohost
deve essere allo stesso livello diinfo
. -
Nel campo
address
della sezionex-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 Cloud Function consentendo solo a ESPv2 di richiamarla, assicurati che il campoaddress
includa il nome della funzione sejwt_audience
non è specificato. Ad esempio:x-google-backend: address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME path_translation: CONSTANT_ADDRESS
Sejwt_audience
è specificato, 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 Cloud Function per l'autenticazione. Il token ID deve avere un valoreaudience
corretto che specifichi l'host e il nome della funzione. ESPv2 impostaaudience
per il token ID utilizzando il valore nel campojwt_audience
se specificato, altrimenti utilizza il campoaddress
. Nel campo
host
, specifica CLOUD_RUN_HOSTNAME, la porzione del nome host dell'URL prenotato sopra in Prenotare un nome host Cloud Run. Non includere l'identificatore di protocollohttps://
. 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 fileopenapi-functions.yaml
:title: Cloud Endpoints + GCF
Il valore della proprietà
title
diventa il nome del servizio Endpoints dopo che hai eseguito il deployment della configurazione.- Salva il documento OpenAPI.
Per informazioni sui campi del documento OpenAPI richiesti dagli endpoint, consulta Configurazione degli endpoint.
Eseguire 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 fileopenapi-functions.yaml
. Il servizio è configurato in base al tuo documento OpenAPI.Durante la creazione e la configurazione del servizio, Service Management invia informazioni al 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 di 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 di configurazione del servizio è costituito da un'indicazione della data seguita 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 del deployment nella pagina Endpoint > Servizi nella console Google Cloud.Se viene visualizzato un messaggio di errore, consulta Risoluzione dei problemi di deployment della configurazione di Endpoints.
Controllo dei servizi richiesti in corso...
Come minimo, Endpoints ed ESP richiedono che siano abilitati i seguenti servizi Google:Nome | Titolo |
---|---|
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
endpoints.googleapis.com |
Google Cloud Endpoints |
Nella maggior parte dei casi, il comando gcloud endpoints services deploy
abilita 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 progetto Google Cloud esistente in cui questi servizi sono stati disabilitati esplicitamente.
Utilizza il comando seguente per confermare che i servizi richiesti siano abilitati:
gcloud services list
Se i servizi richiesti non sono elencati, attivali:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
Abilita anche il servizio Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Per determinare i ENDPOINTS_SERVICE_NAME puoi:
Dopo aver eseguito il deployment della configurazione di Endpoints, vai alla pagina Endpoint nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è visualizzato nella colonna Nome servizio.
Per OpenAPI, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel campo
host
della specifica OpenAPI. Per gRPC, il valore ENDPOINTS_SERVICE_NAME è quello specificato nel camponame
della configurazione degli endpoint gRPC.
Per ulteriori informazioni sui comandi gcloud
, consulta la pagina relativa ai servizi gcloud
.
Creazione di una nuova immagine ESPv2
Crea la configurazione del servizio Endpoints in una nuova immagine Docker ESPv2. In seguito eseguirai il deployment di questa immagine sul servizio Cloud Run riservato.
Per creare la configurazione del servizio in una nuova immagine Docker ESPv2:
Scarica questo script sulla macchina locale in cui è installato gcloud CLI.
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 prenotato sopra in Prenotare un nome host di 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, 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 la release più recente di ESPv2, indicata con 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
Esegui il deployment del servizio Cloud Run ESPv2 con la nuova immagine che hai creato sopra. Sostituisci CLOUD_RUN_SERVICE_NAME con lo stesso nome del servizio Cloud Run che hai utilizzato quando hai prenotato in origine il nome host riportato 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
Se vuoi configurare Endpoints in modo che utilizzi ulteriori opzioni di avvio ESPv2, ad esempio l'abilitazione 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
, inclusi l'elenco delle opzioni disponibili e le informazioni su come specificare più opzioni, vedi Flag per Extensible Service Proxy V2 beta.Concedi a ESPv2 l'autorizzazione a chiamare Service Management e Service Control.
- Nella console Google Cloud, 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 necessarie all'account di servizio:
Concedi a ESPv2 l'autorizzazione per richiamare le tue funzioni. Esegui questo comando per ogni funzione. Nel seguente comando:
- Sostituisci FUNCTION_NAME con il nome della tua funzione e FUNCTION_REGION con la regione in cui viene eseguito 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 cercare l'Account di servizio Compute predefinito, che è 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
- Sostituisci FUNCTION_NAME con il nome della tua funzione e FUNCTION_REGION con la regione in cui viene eseguito il deployment della funzione. Se utilizzi la funzione creata nella
guida rapida all'utilizzo di Google Cloud CLI,
utilizza
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceControllerPer ulteriori informazioni, consulta Cosa sono i ruoli e le autorizzazioni?
Per ulteriori informazioni, consulta Gestione dell'accesso tramite IAM.
Invia richieste all'API
Questa sezione mostra come inviare richieste alla tua API.
- Crea una variabile di ambiente per il nome del servizio Endpoints. Questo è il nome specificato nel campo
host
del 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 mediante la variabile di ambiente ENDPOINTS_HOST
impostata nel passaggio precedente.
curl --request GET \ --header "content-type:application/json" \ "https://${ENDPOINTS_HOST}/hello"
PowerShell
Usa Invoke-WebRequest
per inviare una richiesta HTTP mediante 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 apice inverso. Quando incolli l'esempio in PowerShell, assicurati che non sia presente uno spazio dopo i apici inversi. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nella documentazione di Microsoft.
App di terze parti
Puoi utilizzare un'applicazione di terze parti, come la richiesta di estensione del browser Chrome, Postman.
- Seleziona
GET
come verbo HTTP. - Per l'intestazione, seleziona la chiave
content-type
e il valoreapplication/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 corretta, consulta la sezione Risoluzione dei problemi relativi agli errori di risposta.
Hai appena eseguito il deployment e il test di un'API in Endpoints.
Monitora l'attività dell'API
Visualizza i grafici delle attività per la tua API nella pagina Endpoint > Servizio nella console Google Cloud.
Visualizzare i grafici delle attività di Endpoints
Potrebbero essere necessari alcuni istanti prima che la richiesta venga riportata nei grafici.
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ù, vedi 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 Eliminazione di un'API e istanze API per informazioni sull'interruzione dei servizi utilizzati da questo tutorial.