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

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

Con questa configurazione, ESPv2 intercetta tutte le richieste alle tue funzioni ed esegue controlli necessari (come l'autenticazione) prima di richiamare la funzione. Quando la funzione risponde, ESPv2 raccoglie e segnala dati di telemetria, come mostrato nella figura seguente. Puoi visualizzare le metriche per la tua funzione nella pagina Endpoint > Pagina Servizi nella console Google Cloud.

Architettura di Endpoints

Per una panoramica di Cloud Endpoints, consulta Informazioni sugli endpoint e l'architettura degli endpoint.

Migrazione a ESPv2

Le versioni precedenti di Cloud Endpoints supportavano l'utilizzo di Extensible Service Proxy (ESP) con Cloud Functions. Se hai delle API esistenti di cui vuoi eseguire la migrazione a ESPv2, Per ulteriori informazioni, consulta Eseguire la migrazione a Extensible Service Proxy V2.

Elenco attività

Durante il tutorial, utilizza il seguente elenco di attività. Tutte per completare questo tutorial.

  1. Crea un progetto Google Cloud e, se non hai ancora eseguito il deployment le tue funzioni Cloud Run, il deployment di una funzione di backend di esempio. Vedi Prima di iniziare.
  2. Riserva un nome host Cloud Run per il servizio ESPv2. Consulta Prenotare un nome host Cloud Run.
  3. Crea un Documento OpenAPI che descrive l'API e configurare le route le funzioni di Cloud Run. Consulta Configurazione di Endpoints.
  4. Esegui il deployment del documento OpenAPI per creare un servizio gestito. Consulta Deployment della configurazione di Endpoints.
  5. crea una nuova immagine Docker ESPv2 con i tuoi endpoint la configurazione del servizio. Consulta la sezione Creare una nuova immagine ESPv2.
  6. Esegui il deployment del container ESPv2 su Cloud Run. Quindi concedi a ESPv2 Identity and Access Management (IAM) per richiamare il tuo servizio. Vedi Deployment del container ESPv2.
  7. Richiama una funzione. Consulta Invio di una richiesta all'API.
  8. Monitora l'attività nelle tue funzioni. Consulta Monitoraggio dell'attività dell'API.
  9. 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 le funzioni di Endpoints per Cloud Run, di:

  • Crea un nuovo progetto Google Cloud da utilizzare quando esegui il deployment dal container ESPv2 a Cloud Run.

  • Crea un nuovo progetto o selezionane uno esistente per il tuo le funzioni di Cloud Run.

Per eseguire la configurazione:

  1. Nella console Google Cloud, vai alla pagina Gestisci risorse e creo un progetto.

    Vai alla pagina Gestisci risorse

  2. Verifica che la fatturazione sia attivata per il tuo progetto.

    Scopri come attivare la fatturazione

  3. Prendi nota dell'ID progetto perché sarà necessario in seguito. Per il resto questo ID progetto è noto come ESP_PROJECT_ID.

  4. Prendi nota delle numero progetto perché è necessario più tardi. Nel resto della pagina, questo numero di progetto è indicato come ESP_PROJECT_NUMBER.

  5. Scarica e installa Google Cloud CLI.

    Scarica l'interfaccia a riga di comando gcloud

  6. Se non hai eseguito il deployment delle tue funzioni Cloud Run backend, segui i passaggi Guida rapida: utilizzo di Google Cloud CLI per selezionare o creare un progetto Google Cloud ed eseguire il deployment di personalizzata. Prendi nota della regione e dell'ID progetto in cui le tue funzioni viene eseguito il deployment. Nel resto della 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, dovrai eseguire il deployment di un container di esempio in Cloud Run. Successivamente, eseguirai il deployment del container ESPv2 sullo stesso servizio Cloud Run.

  1. Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati i servizi di machine learning.
    1. Accedi. 
      gcloud auth login
    2. Nella nuova scheda del browser che si apre, scegli un account con l'Editor. o Proprietario nel progetto Google Cloud per cui hai creato eseguendo 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 completamento, il comando visualizza un messaggio simile al seguenti:

    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, eseguirai il deployment di ESPv2 sul servizio Cloud Run CLOUD_RUN_SERVICE_NAME. Specifica CLOUD_RUN_HOSTNAME nel campo host del documento OpenAPI.

Configurazione di Endpoints

Devi disporre di un documento OpenAPI basato su Specifica OpenAPI v2.0 che descrive superficie delle tue funzioni e degli eventuali requisiti di autenticazione. Devi inoltre aggiungere specifico di Google che contiene l'URL di ogni funzione, in modo che ESPv2 dispone delle informazioni necessarie per richiamare una funzione. Se non hanno mai utilizzato OpenAPI, consulta Panoramica di OpenAPI per ulteriori informazioni

  1. Crea un file di testo denominato openapi-functions.yaml. (Per questa pagina si riferisce al documento OpenAPI con quel nome file, ma puoi assegnare un altro nome, se preferisci.
  2. 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
     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 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 funzione Cloud Run consentendo solo ESPv2 per chiamarlo, 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 jwt_audience è specificato, il suo valore deve includere la funzione nome utente. 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 della funzione e il nome della funzione. ESPv2 imposta audience per il token ID utilizzando il valore nell'attributo jwt_audience se specificato, altrimenti utilizza il campo address.

  4. Nel campo host, specifica CLOUD_RUN_HOSTNAME, la parte del nome host dell'URL riservato sopra in Prenotare 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 nel documento OpenAPI che Per gli endpoint è necessario, consulta Configurazione di Endpoints.

esegui il deployment della configurazione di Endpoints

Per eseguire il deployment della configurazione di Endpoints, utilizza gcloud endpoints services deploy . Questo comando utilizza Service Management per creare un'istanza 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 che specificato nel campo host del file openapi-functions.yaml. La configurato in base al documento OpenAPI.

    Durante la creazione e la configurazione del servizio, Service Management genera le informazioni al terminale. Al termine del deployment, verrà visualizzato un messaggio simile a viene visualizzato quanto segue:

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    CONFIG_ID è la configurazione univoca del servizio Endpoints ID 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 una data seguito da un numero di revisione. Se esegui il deployment di openapi-functions.yaml sempre nello stesso giorno, il numero di revisione viene incrementato nell'ID configurazione del servizio. Puoi visualizzare la configurazione del servizio cronologia deployment sugli Endpoint > Servizi nella console Google Cloud.

    Se ricevi 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 seguenti servizi Google da attivare:
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, non abilita i servizi richiesti nelle seguenti circostanze:

  • Se hai utilizzato un'applicazione di terze parti, come Terraform, includono questi servizi.

  • Hai eseguito il deployment della configurazione di Endpoints in una Progetto Google Cloud in cui questi servizi sono stati disattivati esplicitamente.

Utilizza il comando seguente per confermare 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
gcloud services enable endpoints.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 Endpoint nella console Cloud. L'elenco dei possibili ENDPOINTS_SERVICE_NAME è visualizzato 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 gcloud servizi.

Creazione di una nuova immagine ESPv2

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

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

  1. Scarica questo script sulla tua macchina locale su cui è installata l'interfaccia a riga di comando gcloud.

  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 che hai prenotato sopra in Prenotare 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 in una nuova immagine ESPv2 e poi caricare la nuova immagine al Container Registry del tuo 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 servizio Cloud Run utilizzato quando hai prenotato inizialmente 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

  2. Se vuoi configurare gli endpoint in modo da utilizzare Le opzioni di avvio di ESPv2, come 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.

  3. Concedi a ESPv2 l'autorizzazione per chiamare Service Management e Controllo di servizio.

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

      • Vai alla pagina di 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 Cosa sono i ruoli e le autorizzazioni?

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

    • Sostituisci FUNCTION_NAME con il nome del tuo funzione e FUNCTION_REGION con la regione in cui è la funzione in cui è stato eseguito il deployment. Se utilizzi la funzione creata nella guida rapida all'utilizzo di Google Cloud CLI, utilizza helloGET come nome.
    • Sostituisci ESP_PROJECT_NUMBER con number del progetto per cui hai creato ESPv2. Per scoprirlo, puoi andare all' IAM nella console Google Cloud e trova Account di servizio Compute predefinito, ovvero l'account di servizio utilizzato in il 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, vedi Gestione dell'accesso tramite IAM.

invia richieste all'API

Questa sezione mostra come inviare richieste all'API.

  1. Crea una variabile di ambiente per il servizio Endpoints nome. 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

Usa Invoke-WebRequest per inviare una richiesta HTTP mediante ENDPOINTS_HOST la variabile di ambiente 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 accento grave. Quando incolli in PowerShell, assicuratevi che non ci sia uno spazio dopo i accenti arretrati. Per informazioni sulle opzioni utilizzate nella richiesta di esempio, vedi Invoke-WebRequest nel documentazione.

App di terze parti

Puoi utilizzare un'applicazione di terze parti come il browser Chrome estensione Postino richiesta.

  • 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 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 delle attività per l'API sugli Endpoint > Servizio nella console Google Cloud.

    Visualizzare i grafici delle attività di Endpoints

    Potrebbero essere necessari alcuni minuti prima che la richiesta venga riportata nei grafici.

  2. Controlla i log delle richieste per l'API nella pagina Esplora log. Visualizza i log delle richieste di Endpoints

Creazione di un portale per gli sviluppatori per l'API

Puoi usare il portale Cloud Endpoints per creare un portale per 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 di istanze API per informazioni sull'interruzione dei servizi utilizzati da questo tutorial.

Passaggi successivi