Introduzione ad API Gateway e Cloud Run per gRPC

Questa pagina mostra come configurare API Gateway per gestire e proteggere un servizio di backend Cloud Run con gRPC.

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 Cloud Run con gRPC.

  1. Crea o seleziona un Google Cloud progetto.
  2. Se non hai eseguito il deployment di Cloud Run, esegui il deployment di un servizio gRPC di backend di esempio. Vedi il passaggio 7 in Prima di iniziare.
  3. Abilita i servizi API Gateway richiesti.
  4. Crea un documento di configurazione dell'API gRPC che descriva la tua API e configuri le route a Cloud Run. Consulta Configurazione di una configurazione API con gRPC.
  5. Esegui il deployment di un gateway API utilizzando la configurazione API. Consulta Deployment di un gateway API.
  6. Testa il deployment dell'API inviando una richiesta. Consulta Invio di una richiesta all'API.
  7. Monitorare l'attività sui tuoi servizi. 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 Dashboard

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

    Abilita fatturazione

  3. Prendi nota dell'ID progetto perché ti servirà in seguito. Nel resto di questa pagina, questo ID progetto è indicato come PROJECT_ID.

  4. Prendi nota del numero di progetto perché ti servirà in seguito. Nel resto di questa pagina, questo numero di progetto è indicato come PROJECT_NUMBER.

  5. Scarica e installa Google Cloud CLI.

    Scarica gcloud CLI

  6. Segui i passaggi descritti nella guida rapida di gRPC Python per installare gRPC e gli strumenti gRPC.

  7. Esegui il deployment del servizio gRPC Cloud Run di backend di esempio python-grpc-bookstore-server da utilizzare con questo tutorial. Il servizio gRPC utilizza la seguente immagine container:

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Segui i passaggi descritti in Guida rapida: eseguire il deployment di un container di esempio preimpostato per eseguire il deployment del servizio. Assicurati di sostituire l'immagine container specificata nella guida rapida con gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Prendi nota dell'URL del servizio, nonché della regione e dell'ID progetto in cui è stato eseguito il deployment del servizio.

Attivazione dei 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.

Creazione di una configurazione API con gRPC

L'esempio bookstore-grpc contiene i file che devi copiare localmente e configurare.

  1. Crea un file descrittore protobuf autonomo dal file .proto del servizio:
    1. Salva una copia di bookstore.proto dal repository di esempio nella tua directory di lavoro corrente. Questo file definisce l'API del servizio Bookstore.
    2. Crea la seguente directory nella directory di lavoro: mkdir generated_pb2
    3. Crea il file descrittore, api_descriptor.pb, utilizzando il compilatore di buffer di protocollo protoc. Esegui questo comando nella directory in cui hai salvato bookstore.proto: 
      python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto

      Nel comando precedente, --proto_path è impostato sulla directory di lavoro corrente. Nell'ambiente di compilazione gRPC, se utilizzi una directory diversa per i file di input .proto, modifica --proto_path in modo che il compilatore esegua la ricerca nella directory in cui hai salvato bookstore.proto.

  2. Crea un file di testo denominato api_config.yaml nella directory di lavoro attuale (la stessa directory che contiene bookstore.proto). Per comodità, questa pagina fa riferimento al documento di configurazione dell'API gRPC con questo nome file, ma puoi assegnargli un altro nome, se preferisci. Aggiungi i seguenti contenuti al file: 
    # The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app
     Il rientro è importante per il formato YAML. Ad esempio, il campo name deve trovarsi allo stesso livello di type.
  3. Nel campo name, un servizio denominato *.apigateway.PROJECT_ID.cloud.goog dove PROJECT_ID è il nome del tuo ID progetto Google Cloud .

  4. Nel campo address della sezione backend.rules, sostituisci grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app con l'URL effettivo del servizio gRPC Cloud Run di backend python-grpc-bookstore-server, dove HASH è il codice hash univoco generato al momento della creazione del servizio.

    Questo esempio presuppone che tu stia utilizzando il servizio di backend gRPC Bookstore creato in Prima di iniziare. Se necessario, sostituisci questo valore con l'URL del tuo servizio Cloud Run.

  5. Salva il documento di configurazione dell'API gRPC.
  6. Crea la configurazione API: 
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     where:
    • CONFIG_ID specifica il nome della configurazione API.
    • API_ID specifica il nome dell'API.
    Ad esempio: 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

Deployment di un gateway API

Per eseguire il deployment della configurazione API gRPC in un gateway, esegui questo comando:

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.

Ad esempio:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

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.

Ad esempio: 

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

Invio di una richiesta all'API

Per inviare richieste all'API di esempio, puoi utilizzare un client gRPC di esempio scritto in Python.

  1. Clona il repository Git in cui è ospitato il codice client gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

  2. Cambia la directory di lavoro:

    cd python-docs-samples/endpoints/bookstore-grpc/

  3. Installa le dipendenze:

    pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

  4. Invia una richiesta all'API di esempio:

    python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

    Specifica la proprietà defaultHostname del gateway in DEFAULT_HOSTNAME, senza l'identificatore del protocollo. Ad esempio:

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

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

Hai eseguito il deployment e il test di un'API in API Gateway con gRPC.

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.