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à
Durante il tutorial, utilizza il seguente elenco di attività. Tutte le attività sono necessarie per eseguire il deployment di un API Gateway per il tuo servizio di backend Cloud Run con gRPC.
- Crea o seleziona un progetto Google Cloud.
- Se non hai eseguito il deployment di Cloud Run, esegui il deployment di un servizio gRPC di backend di esempio. Vedi il passaggio 7 della sezione Prima di iniziare.
- Attiva i servizi API Gateway richiesti.
- Crea un documento di configurazione dell'API gRPC che descriva l'API e configuri le route per Cloud Run. Consulta Configurazione di una configurazione API con gRPC.
- Esegui il deployment di un API Gateway utilizzando la configurazione API. Consulta Deployment di un API Gateway.
- Testa il deployment dell'API inviando una richiesta. Consulta Invio di una richiesta all'API.
- Monitora l'attività relativa ai tuoi servizi. Consulta Monitoraggio dell'attività dell'API.
- Evita che al tuo account Google Cloud vengano addebitati costi. Consulta Pulizia.
Prima di iniziare
Nella console Google Cloud, vai alla pagina Dashboard e seleziona o crea un progetto Google Cloud.
Verifica che la fatturazione sia attivata per il tuo progetto.
Prendi nota dell'ID progetto perché sarà necessario in seguito. Nel resto della pagina, questo ID progetto è indicato come PROJECT_ID.
Prendi nota del numero di progetto perché sarà necessario in seguito. Nel resto della pagina, questo numero di progetto è indicato come PROJECT_NUMBER.
Scarica e installa Google Cloud CLI.
Segui i passaggi nella guida rapida per Python gRPC per installare gli strumenti gRPC e gRPC.
Esegui il deployment del servizio di backend gRPC Cloud Run di esempio python-grpc-bookstore-server da utilizzare in 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: deployment di un container predefinito di esempio per eseguire il deployment del servizio. Assicurati di sostituire l'immagine container specificata in questa guida rapida con
gcr.io/endpointsv2/python-grpc-bookstore-server:2
Prendi nota dell'URL del servizio, della regione e dell'ID progetto in cui viene eseguito il deployment del servizio.
Abilitazione 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 |
Per verificare che i servizi richiesti siano abilitati:
gcloud services list
Se non vedi elencati i servizi richiesti, abilitali:
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Per ulteriori informazioni sui servizi gcloud
, consulta la pagina relativa ai servizi gcloud
.
Creazione di una configurazione API con gRPC
L'esempio di bookstore-grpc
contiene i file che devi copiare localmente e configurare.
- Crea un file descrittore protobuf autonomo dal file
.proto
del servizio:- Salva una copia di
bookstore.proto
dal repository di esempio nella directory di lavoro attuale. Questo file definisce l'API del servizio Libreria. - Crea la seguente directory nella directory di lavoro:
mkdir generated_pb2
- Crea il file descrittore,
api_descriptor.pb
, utilizzando il compilatore del buffer di protocolloprotoc
. Esegui questo comando nella directory in cui hai salvatobookstore.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 attuale. Nel tuo ambiente di build gRPC, se utilizzi una directory diversa per i file di input.proto
, modifica--proto_path
in modo che il compilatore cerchi nella directory in cui hai salvatobookstore.proto
.
- Salva una copia di
-
Crea un file di testo denominato
api_config.yaml
nella directory di lavoro attuale (la stessa directory che contienebookstore.proto
). Per comodità, questa pagina si riferisce al documento di configurazione dell'API gRPC con il nome del file, ma puoi assegnare 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 camponame
deve essere allo stesso livello ditype
. Nel campo
name
, un servizio denominato*.apigateway.PROJECT_ID.cloud.goog
dove PROJECT_ID è il nome dell'ID progetto Google Cloud.Nel campo
address
della sezionebackend.rules
, sostituisci grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app con l'URL effettivo del servizio Cloud Run gRPC di backend python-grpc-bookstore-server, dove HASH è il codice hash univoco generato al momento della creazione del servizio.Questo esempio presuppone che utilizzi il servizio di backend gRPC Bookstore creato nella sezione Prima di iniziare. Se necessario, sostituisci questo valore con l'URL del tuo servizio Cloud Run.
- Salva il documento di configurazione dell'API gRPC.
- Crea la configurazione API:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --project=PROJECT_ID \ --grpc-files=api_descriptor.pb,api_config.yaml
dove:- CONFIG_ID specifica il nome della configurazione API.
- API_ID specifica il nome dell'API.
- PROJECT_ID specifica il nome del tuo progetto Google Cloud.
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 API Gateway
Per eseguire il deployment della configurazione dell'API gRPC su un gateway, esegui questo comando:
gcloud api-gateway gateways create GATEWAY_ID \ --api=API_ID --api-config=CONFIG_ID \ --location=GCP_REGION --project=PROJECT_ID
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 nel gateway.
GCP_REGION è la regione di Google Cloud per il gateway di cui è stato eseguito il deployment.
PROJECT_ID specifica il nome del tuo progetto Google Cloud.
Ad esempio:
gcloud api-gateway gateways create bookstore-grpc \ --api=grpc-test --api-config=grpc-config \ --location=us-central1 --project=my-project
Una volta completato, puoi utilizzare il comando seguente per visualizzare i dettagli sul gateway:
gcloud api-gateway gateways describe GATEWAY_ID \ --location=GCP_REGION --project=PROJECT_ID
Prendi nota del valore della proprietà defaultHostname
nell'output di questo comando. Si tratta della parte del nome host dell'URL del gateway che utilizzi 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.
Clona il repository git in cui è ospitato il codice client gRPC:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Cambia la directory di lavoro:
cd python-docs-samples/endpoints/bookstore-grpc/
Installa le dipendenze:
pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt
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 di protocollo. Ad esempio:python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true
monitora l'attività dell'API
Visualizza i grafici di attività per l'API nella pagina Gateway API della console Google Cloud. Fai clic sull'API per visualizzare i relativi grafici di attività nella pagina Panoramica. La visualizzazione dei dati relativi alle richieste nei grafici può richiedere alcuni minuti.
Controlla i log delle richieste per l'API nella pagina Esplora log. Puoi trovare un link alla pagina Esplora log nella pagina Gateway API della console Google Cloud.
Vai alla pagina di API Gateway
Quando ti trovi nella pagina API Gateway:- Seleziona l'API da visualizzare.
- Fai clic sulla scheda Dettagli.
- Fai clic sul link sotto 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.