Questa pagina è stata tradotta dall'API Cloud Translation.

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 descrive l'API e configura le route in 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.
Vai alla pagina Dashboard

Nota: se non prevedi di conservare le risorse create in questo tutorial, crea un nuovo progetto anziché selezionarne uno esistente. Una volta completati questi passaggi, puoi eliminare il progetto rimuovendo tutte le risorse associate.
Verifica che la fatturazione sia attivata per il tuo progetto.
Scopri come attivare la fatturazione
Prendi nota dell'ID progetto perché sarà necessario in seguito. Per il resto questo ID progetto è noto come PROJECT_ID.
Prendi nota delle numero progetto perché è necessario più tardi. Nel resto della pagina, questo numero di progetto è denominata PROJECT_NUMBER.
Scarica e installa Google Cloud CLI.
Scarica gcloud CLI
Segui i passaggi nella Guida rapida di gRPC Python per installare gRPC e gli strumenti gRPC.
Esegui il deployment del backend di esempio python-grpc-bookstore-server Servizio Cloud Run gRPC 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 di esempio predefinito 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.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Per ulteriori informazioni sui servizi gcloud, vedi gcloud servizi.

Creazione di una configurazione API con gRPC

La bookstore-grpc contiene i file che devi copiare localmente e configurare.

Crea un file descrittore protobuf autonomo dal file .proto del servizio:
1. Salva una copia di bookstore.proto dal repository di esempio alla directory di lavoro attuale. Questo file definisce l'API del servizio Libreria.
2. Crea la seguente directory nella directory di lavoro: mkdir generated_pb2
3. Crea il file descrittore, api_descriptor.pb, utilizzando il metodo Il protocollo protoc memorizza il compilatore nel buffer. Esegui questo comando 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 sul valore attuale nella directory di lavoro. Nel tuo ambiente di build gRPC, se utilizzi un'interfaccia per i file di input .proto, modifica --proto_path in modo che il compilatore cerca nella directory in cui hai salvato bookstore.proto.

Crea un file di testo denominato api_config.yaml nella directory di lavoro attuale (la stessa directory che contiene bookstore.proto). Per per praticità, questa pagina fa riferimento al documento di configurazione dell'API gRPC nome del file, ma puoi assegnargli un altro nome, se preferisci. Aggiungi quanto segue i contenuti del 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, name deve essere allo stesso livello di type.

Nel campo name, un servizio denominato *.apigateway.PROJECT_ID.cloud.goog dove PROJECT_ID è il nome del tuo ID progetto Google Cloud.
Nel campo address nella sezione backend.rules sostituisci grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app con la sezione URL del servizio Cloud Run gRPC di backend python-grpc-bookstore-server, dove HASH è il codice hash univoco generato al momento della creazione del servizio.

Nota: Per utilizzare gRPC con TLS su Cloud Run, il campo address deve hanno lo schema grpcs:// anziché https://.

Questo esempio presuppone che tu stia utilizzando il backend gRPC Bookstore creato in 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.

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 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.
Nota:
i valori consentiti sono:
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
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 API Gateway nell' nella console Google Cloud. Fai clic sulla tua API per visualizzarne i grafici di attività nella Panoramica. L'applicazione delle richieste potrebbe richiedere qualche istante nei grafici.
Controlla i log delle richieste per l'API nella pagina Esplora log. Un link alla sezione La pagina Esplora log è disponibile nella pagina Gateway API nella nella console Google Cloud.
Vai alla pagina di API Gateway
Quando ti trovi nella pagina API Gateway:
1. Seleziona l'API da visualizzare.
2. Fai clic sulla scheda Dettagli.
3. 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.