Introduzione ad API Gateway e App Engine

Questa pagina mostra come configurare API Gateway per gestire e proteggere un servizio di backend App Engine.

Elenco attività

Utilizza il seguente elenco di attività mentre segui il tutorial. Tutte le attività sono necessarie per eseguire il deployment di un gateway API per il servizio di backend App Engine.

  1. Crea o seleziona un Google Cloud progetto.
  2. Se non hai eseguito il deployment della tua app App Engine, esegui il deployment di un'app di esempio. Consulta la sezione Prima di iniziare.
  3. Abilita i servizi API Gateway richiesti.
  4. Configura IAP per proteggere la tua app. Vedi Configurare IAP.
  5. Crea una descrizione OpenAPI che descriva la tua API e configura le route per App Engine. Consulta Crea una configurazione API.
  6. Esegui il deployment di un gateway API utilizzando la configurazione API. Consulta Deployment di un gateway API.
  7. Monitorare l'attività nelle tue app. Consulta Monitorare l'attività dell'API.
  8. Evita che al tuo account Google Cloud vengano addebitati costi. Vedi Pulizia.

Prima di iniziare

  1. Nella console Google Cloud , vai alla pagina Dashboard e seleziona o crea un progetto Google Cloud .

    Vai alla pagina Dashboard

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

    Abilita fatturazione

  3. Prendi nota dell'ID progetto che vuoi utilizzare per questo tutorial. Nel resto di questa pagina, questo ID progetto viene indicato come PROJECT_ID.

  4. Scarica e installa Google Cloud CLI.

    Scarica gcloud CLI

  5. Aggiorna i gcloudcomponenti:

    gcloud components update

  6. Imposta il progetto predefinito. Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud :

    gcloud config set project PROJECT_ID

  7. Se non hai eseguito il deployment della tua app App Engine, segui i passaggi descritti nella guida rapida di App Engine per la tua lingua per utilizzare Google Cloud CLI per selezionare o creare un progetto Google Cloud ed eseguire il deployment di un'app di esempio. Prendi nota dell'URL dell'app, nonché della regione e dell'ID progetto in cui è stato eseguito il deployment dell'app.

Attivare i servizi richiesti

API Gateway richiede l'abilitazione dei seguenti servizi Google:

Nome Titolo
apigateway.googleapis.com API API Gateway
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control

Utilizza i seguenti comandi per abilitare questi servizi: 

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Per saperne di più sui servizi gcloud, consulta Servizi gcloud.

Configurare IAP per proteggere la tua app

Per proteggere la tua app App Engine, devi utilizzare Identity Aware Proxy (IAP) per verificare che le richieste siano autenticate. Questo processo include la specifica dei membri a cui deve essere concesso il ruolo IAP-secured Web App User richiesto per il progetto.

Segui i passaggi per abilitare IAP e verifica di poter accedere alla tua applicazione.

Crea una configurazione API

Prima di poter utilizzare API Gateway per gestire il traffico verso il backend App Engine di cui hai eseguito il deployment, è necessaria una configurazione API.

Puoi creare una configurazione API utilizzando una descrizione OpenAPI che contiene annotazioni specializzate per definire il comportamento scelto di API Gateway. Devi aggiungere un campo specifico di Google che contenga l'URL di ogni app App Engine in modo che API Gateway disponga delle informazioni necessarie per richiamare un'app.

Per maggiori dettagli sulle estensioni OpenAPI supportate, vedi quanto segue:

Per creare la configurazione API:

  1. Crea un file di testo denominato openapi-appengine.yaml. Per praticità, questa pagina fa riferimento alla descrizione OpenAPI con questo nome file, ma puoi chiamarlo in un altro modo, se preferisci.
  2. Copia i contenuti del seguente file nel file openapi-run.yaml:

    OpenAPI 2.0

    # openapi-appengine.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with an App Engine backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: APP_URL
        jwt_audience: IAP_CLIENT_ID
      responses:
        '200':
          description: A successful response
          schema:
            type: string
    • Nel campo title, sostituisci API_ID con il nome della tua API e optional-string con una breve descrizione a tua scelta. Se la tua API non esiste ancora, il comando per creare la configurazione API creerà anche l'API con il nome che specifichi. Il valore del campo title viene utilizzato per creare chiavi API che concedono l'accesso a questa API. Per le linee guida per la denominazione delle API, consulta Requisiti per l'ID API.
    • Nel campo address della sezione x-google-backend, sostituisci APP_URL con l'URL effettivo del servizio App Engine (il percorso completo dell'API chiamata). Ad esempio: https://myapp.an.r.appspot.com/hello.

      Sostituisci IAP_CLIENT_ID con l'ID client OAuth che hai creato durante la configurazione di IAP.

    OpenAPI 3.x

    # openapi-appengine.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with an App Engine backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    appengine_backend:
      address: APP_URL
      jwtAudience: IAP_CLIENT_ID
      deadline: 30.0
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: appengine_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string
    • Nel campo title, sostituisci API_ID con il nome della tua API e optional-string con una breve descrizione a tua scelta. Se la tua API non esiste ancora, il comando per creare la configurazione API creerà anche l'API con il nome che specifichi. Il valore del campo title viene utilizzato per creare chiavi API che concedono l'accesso a questa API. Per le linee guida per la denominazione delle API, consulta Requisiti per l'ID API.
    • Nel campo address, sostituisci APP_URL con l'URL effettivo del tuo servizio App Engine (il percorso completo dell'API chiamata). Ad esempio: https://myapp.an.r.appspot.com/hello.

      Sostituisci IAP_CLIENT_ID con l'ID client OAuth che hai creato durante la configurazione di IAP.
  3. Inserisci il seguente comando, dove:
    • CONFIG_ID specifica il nome della configurazione API.
    • API_ID specifica il nome dell'API. Se l'API non esiste già, questo comando la crea.
    • SERVICE_ACCOUNT_EMAIL specifica il account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata.
    gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-appengine.yaml \
 --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    Il completamento di questa operazione potrebbe richiedere diversi minuti, poiché la configurazione dell'API viene propagata ai sistemi downstream. La creazione di una configurazione API complessa potrebbe richiedere fino a 10 minuti per essere completata correttamente.

  4. Una volta creata la configurazione API, puoi visualizzarne i dettagli eseguendo questo comando: 
    gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

Deployment di un gateway API

Ora puoi eseguire il deployment dell'API su API Gateway. Il deployment di un'API su API Gateway definisce anche un URL esterno che i client API possono utilizzare per accedere all'API.

Esegui questo comando per eseguire il deployment della configurazione API appena creata in API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

Dove:

  • GATEWAY_ID specifica il nome del gateway.
  • API_ID specifica il nome dell'API API Gateway associata a questo gateway.
  • CONFIG_ID specifica il nome della configurazione API di cui è stato eseguito il deployment sul gateway.

  • GCP_REGION è la regioneGoogle Cloud del gateway di cui è stato eseguito il deployment.

Al termine, puoi utilizzare questo comando per visualizzare i dettagli del gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

Prendi nota del valore della proprietà defaultHostname nell'output di questo comando. Questa è la parte del nome host dell'URL del gateway che utilizzerai per testare il deployment nel passaggio successivo.

Testare il deployment dell'API

Ora puoi inviare richieste all'API utilizzando l'URL generato al momento del deployment del gateway.

Inserisci questo comando curl, dove:

  • DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment. Il valore di defaultHostname si trova nell'output del comando gateways describe mostrato in precedenza.
  • DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment. Il valore di defaultHostname si trova nell'output del comando gateways describe mostrato in precedenza.
  • hello è il percorso specificato nella configurazione API.
curl https://DEFAULT_HOSTNAME/hello

Ad esempio: 

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Dovresti vedere l'output seguente:

My-AppEngineApp: Access denied for user gateway-1a2b3c@04d5e6f35FgdsT73dFrty-tp.iam.gserviceaccount.com requesting https://my-project.appspot.com/helloGET. If you should have access, contact myldap@google.com and include the full text of this message.

Operazione riuscita. Il gateway gestisce l'accesso al servizio di backend App Engine. Per concedere l'accesso alla tua app App Engine, devi configurare un service account con le autorizzazioni corrette per il tuo gateway.

monitora l'attività dell'API

  1. Visualizza i grafici delle attività per la tua API nella pagina API Gateway della consoleGoogle Cloud . Fai clic sull'API per visualizzare i grafici delle attività nella pagina Panoramica. 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. Un link alla pagina Esplora log è disponibile nella pagina API Gateway della consoleGoogle Cloud .

    Vai alla pagina API Gateway.

    Una volta nella pagina API Gateway:

    1. Seleziona l'API da visualizzare.
    2. Fai clic sulla scheda Dettagli.
    3. Fai clic sul link nella sezione Log.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa guida rapida, puoi:

In alternativa, puoi anche eliminare il progetto Google Cloud utilizzato per questo tutorial.