Configurazione di Cloud Endpoints OpenAPI per l'ambiente standard con ESPv2

Questa pagina mostra come configurare Cloud Endpoints per App Engine. Endpoints utilizza Extensible Service Proxy V2 (ESPv2) come gateway API. Per fornire la gestione delle API per App Engine, esegui il deployment del container ESPv2 predefinito in Cloud Run. Quindi proteggi l'app utilizzando Identity Aware Proxy (IAP) in modo che solo ESPv2 possa richiamarla.

Una volta configurata, ESPv2 intercetta tutte le richieste alla tua app ed esegue tutti i controlli necessari (ad esempio l'autenticazione) prima di richiamare l'app. Quando l'app risponde, ESPv2 raccoglie e segnala la telemetria, come mostrato nella figura di seguito. Puoi visualizzare le metriche per la tua app nella pagina Endpoint > Servizi nella console Google Cloud.

Architettura degli endpoint

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 Run. 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. Tutte le attività sono necessarie affinché Endpoints possa gestire l'app.

Crea un progetto Google Cloud e, se non hai eseguito il deployment del tuo App Engine, esegui il deployment di un'app di backend di esempio. Vedi Prima di iniziare.
Configura IAP per proteggere l'app. Vedi Configurare IAP.
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 al tuo App Engine. 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.
Richiama l'app. Vedi Inviare una richiesta all'API.
Monitora l'attività relativa alle tue app. Consulta Monitoraggio dell'attività dell'API.
Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

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

Per effettuare 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 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.
Scarica gcloud CLI
Se non hai eseguito il deployment del tuo backend App Engine, segui i passaggi nella guida rapida di App Engine. Prendi nota della regione e dell'ID progetto in cui viene eseguito il deployment delle tue app. Nel resto di questa pagina, questo ID progetto è indicato come APP_PROJECT_ID.

Configura IAP per proteggere la tua app

Per proteggere la tua app App Engine, devi utilizzare Identity Aware Proxy (IAP) per garantire che le richieste siano autenticate.

Segui la procedura per abilitare IAP e assicurati di essere in grado di accedere alla tua applicazione.

Inoltre, durante la configurazione del client OAuth, prendi nota di OAuth client_id, che in questo tutorial verrà indicato come IAP_CLIENT_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.
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 eseguire 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

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 e gateway-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 app ed eventuali requisiti di autenticazione. Devi inoltre aggiungere un campo specifico di Google contenente l'URL di ogni app, in modo che l'ESPv2 disponga delle informazioni necessarie per richiamare un'app. Se non hai mai utilizzato OpenAPI, consulta la panoramica di OpenAPI per ulteriori informazioni.

Crea un file di testo denominato openapi-appengine.yaml. Per praticità, questa pagina fa riferimento al documento OpenAPI con quel nome di file, ma puoi nominarlo con un altro nome, se preferisci.

L'app di backend App Engine viene definita nella parte superiore del file openapi-appengine.yaml, in una definizione di tipo x-google-backend. Ad esempio:

  swagger: '2.0'
  info:
    title: Cloud Endpoints + App Engine
    description: Sample API on Cloud Endpoints with an App Engine backend
    version: 1.0.0
  host: CLOUD_RUN_HOSTNAME
  schemes:
    - https
  produces:
    - application/json
  x-google-backend:
    address: https://APP_PROJECT_ID.REGION.r.appspot.com
    jwt_audience: IAP_CLIENT_ID
    protocol: h2
  paths:
    /:
      get:
        summary: Greet a user
        operationId: hello
        responses:
          '200':
            description: A successful response
            schema:
              type: string

Il rientro è importante per il formato YAML. Ad esempio, il campo host deve essere allo stesso livello di info.

Nel campo address della sezione x-google-backend, sostituisci APP_PROJECT_ID con l'ID del tuo progetto Google Cloud, REGION con la regione della piattaforma Google Cloud in cui hai eseguito il deployment di App Engine e IAP_CLIENT_ID con l'ID client OAuth creato al momento della configurazione di IAP.
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 protocollo https://. Ad esempio:
```
swagger: '2.0'
  info:
    title: Cloud Endpoints + App Engine
    description: Sample API on Cloud Endpoints with an App Engine backend
    version: 1.0.0
  host: gateway-12345-uc.a.run.app
```
Prendi nota del valore della proprietà title nel file openapi-appengine.yaml:
```
title: Cloud Endpoints + App Engine
```
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-appengine.yaml \
  --project ESP_PROJECT_ID
```
Viene creato un nuovo servizio Endpoints con il nome specificato nel campo host del file openapi-appengine.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-appengine.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.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 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 campo name 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.

Nota:

Questo passaggio è obbligatorio.

La configurazione del servizio deve essere incorporata in una nuova immagine Docker perché Cloud Run è un servizio scale-to-zero. Ciò significa che quando non c'è traffico, tutte le istanze vengono eliminate. Quando il traffico aumenta, vengono create nuove istanze on demand. Questo tipo di creazione di istanze di servizio è anche chiamato avvio a freddo. Per saperne di più, consulta la documentazione sulla contemporaneità di Cloud Run.

Se l'immagine Docker non aveva la configurazione del servizio incorporata, Cloud Run dovrebbe effettuare due chiamate API a Google ServiceManagement all'avvio a freddo. Queste chiamate vengono conteggiate ai fini della quota dell'API Google ServiceManagement.

Creando la configurazione del servizio nell'immagine Docker ESPv2, rimuovi le due chiamate API ed eviterai di influire sul conteggio della quota per il servizio Google ServiceManagement. Questo passaggio accelera inoltre la creazione di nuove istanze di servizio e riduce la latenza per le richieste in attesa della nuova istanza.

Devi eseguire nuovamente l'intero passaggio ed eseguire nuovamente il deployment del nuovo container:

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, il deployment della versione precedente di ESPv2 verrà mantenuto.

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

Scarica questo script sulla macchina locale in cui è installato gcloud CLI.

Nota:
Questo script richiede bash. Se non utilizzi macOS/Linux, puoi eseguirlo su Cloud Shell, Compute Engine o sottosistema Windows per 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 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"
```
Nota:
Passa il flag -z allo script per generare l'immagine in una posizione del Registro di sistema diversa.

Ad esempio, per eseguire il push dell'immagine ESPv2 generata in 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 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
```
Nota:
Se vuoi che ESPv2 gestisca l'accesso, usa 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 dal server IAM del <a=" docs="" Managing-access"="" run="" secure="">controllo dell'accesso di Cloud Run. Poiché IAM ed ESPv2 utilizzano la stessa intestazione di autorizzazione, non funzionano insieme, assicurati di utilizzarne solo una. Consiglia di utilizzare IAM anziché ESPv2 per la gestione dell'accesso.</a=">
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, consulta la sezione Flag per Extensible Service Proxy V2.
Concedi l'autorizzazione ESPv2 per richiamare la tua app protetta IAP. Esegui questo comando per ciascun servizio. Nel seguente comando:
- Sostituisci APP_PROJECT_ID con il nome del tuo ID progetto App Engine.
- Sostituisci ESP_PROJECT_NUMBER con il numero del progetto che hai creato per ESPv2. Per trovarlo, vai alla console IAM e cerca l'account di servizio predefinito di Compute Engine, ovvero l'account di servizio utilizzato nel flag "member".
```
  gcloud projects add-iam-policy-binding APP_PROJECT_ID \
      --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/iap.httpsResourceAccessor"
    
```

Per ulteriori informazioni, consulta Gestione dell'accesso utilizzando 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}/"

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/").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 valore application/json.
Utilizza l'URL effettivo anziché la variabile di ambiente, ad esempio:
```
https://gateway-12345-uc.a.run.app/
```

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.