Introdução ao API Gateway e ao Cloud Run para gRPC

Esta página mostra como configurar o API Gateway para gerir e proteger um serviço de back-end do Cloud Run com gRPC.

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para implementar um gateway de API para o seu serviço de back-end do Cloud Run com gRPC.

  1. Crie ou selecione um Google Cloud projeto.
  2. Se não tiver implementado o seu próprio Cloud Run, implemente um serviço gRPC de back-end de exemplo. Consulte o passo 7 em Antes de começar.
  3. Ative os serviços do gateway da API necessários.
  4. Crie um documento de configuração da API gRPC que descreve a sua API e configura as rotas para o Cloud Run. Consulte o artigo Configurar uma configuração de API com gRPC.
  5. Implemente um gateway de API através da configuração da API. Consulte o artigo Implementar um gateway da API.
  6. Teste a implementação da API enviando um pedido. Consulte o artigo Enviar um pedido para a API.
  7. Monitorize a atividade nos seus serviços. Consulte o artigo Acompanhamento da atividade da API.
  8. Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.

Antes de começar

  1. Na Google Cloud consola, aceda à página Painel de controlo e selecione ou crie um Google Cloud projeto.

    Aceder ao painel de controlo

  2. Certifique-se de que a faturação está ativada para o seu projeto.

    Ative a faturação

  3. Tome nota do ID do projeto, uma vez que é necessário mais tarde. No resto desta página, o ID do projeto é referido como PROJECT_ID.

  4. Tome nota do número do projeto porque é necessário mais tarde. No resto desta página, este número do projeto é denominado PROJECT_NUMBER.

  5. Transfira e instale a Google Cloud CLI.

    Transfira a CLI gcloud

  6. Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas gRPC.

  7. Implemente o exemplo de back-end python-grpc-bookstore-server serviço do Cloud Run gRPC para utilização com este tutorial. O serviço gRPC usa a seguinte imagem do contentor:

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

    Siga os passos no artigo Início rápido: implemente um contentor de exemplo pré-criado para implementar o serviço. Certifique-se de que substitui a imagem do contentor especificada nesse início rápido por gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Tome nota do URL do serviço, bem como da região e do ID do projeto onde o serviço está implementado.

Ativar serviços necessários

O API Gateway requer que ative os seguintes serviços Google:

Nome Título
apigateway.googleapis.com API do API Gateway
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

Para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

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

Para mais informações sobre os serviços gcloud, consulte os serviços gcloud.

Criar uma configuração de API com gRPC

O exemplo bookstore-grpc contém os ficheiros que tem de copiar localmente e configurar.

  1. Crie um ficheiro de descritor protobuf autónomo a partir do ficheiro .proto do seu serviço:
    1. Guarde uma cópia de bookstore.proto do repositório de exemplo no seu diretório de trabalho atual. Este ficheiro define a API do serviço Bookstore.
    2. Crie o seguinte diretório no seu diretório de trabalho: mkdir generated_pb2
    3. Crie o ficheiro de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde guardou 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

      No comando anterior, --proto_path está definido como o diretório de trabalho atual. No seu ambiente de compilação gRPC, se usar um diretório diferente para os ficheiros de entrada .proto, altere --proto_path para que o compilador pesquise o diretório onde guardou bookstore.proto.

  2. Crie um ficheiro de texto denominado api_config.yaml no seu diretório de trabalho atual (o mesmo diretório que contém bookstore.proto). Para maior conveniência, esta página refere-se ao documento de configuração da API gRPC por esse nome de ficheiro, mas pode atribuir-lhe outro nome, se preferir. Adicione o seguinte conteúdo ao ficheiro: 
    # 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
     A indentação é importante para o formato YAML. Por exemplo, o campo name tem de estar ao mesmo nível que type.
  3. No campo name, um serviço denominado *.apigateway.PROJECT_ID.cloud.goog em que PROJECT_ID é o nome do seu Google Cloud ID do projeto.

  4. No campo address na secção backend.rules, substitua grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app pelo URL real do serviço do Cloud Run gRPC de back-end python-grpc-bookstore-server, em que HASH é o código hash exclusivo gerado quando criou o serviço.

    Este exemplo pressupõe que está a usar o serviço de back-end da livraria gRPC criado em Antes de começar. Se necessário, substitua este valor pelo URL do seu serviço do Cloud Run.

  5. Guarde o documento de configuração da API gRPC.
  6. Crie a configuração da API: 
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     where:
    • CONFIG_ID especifica o nome da configuração da API.
    • API_ID especifica o nome da sua API.
    • PROJECT_ID especifica o nome do seu Google Cloud projeto.
    Por exemplo: 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

Implementar um gateway da API

Para implementar a configuração da API gRPC num gateway, execute o seguinte comando:

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

where:

  • GATEWAY_ID especifica o nome da gateway.
  • API_ID especifica o nome da API do gateway da API associada a este gateway.
  • CONFIG_ID especifica o nome da configuração da API implementada no gateway.

  • GCP_REGION é a Google Cloud região para o gateway implementado.

  • PROJECT_ID especifica o nome do seu Google Cloud projeto.

Por exemplo:

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

Após a conclusão com êxito, pode usar o seguinte comando para ver detalhes sobre o gateway:

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

Anote o valor da propriedade defaultHostname no resultado deste comando. Esta é a parte do nome do anfitrião do URL do gateway que usa para testar a implementação no passo seguinte.

Por exemplo: 

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

Enviar um pedido para a API

Para enviar pedidos para a API de exemplo, pode usar um cliente gRPC de exemplo escrito em Python.

  1. Clone o repositório Git onde o código do cliente gRPC está alojado:

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

  2. Altere o diretório de trabalho:

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

  3. Instalar dependências:

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

  4. Envie um pedido para a API de exemplo:

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

    Especifique a propriedade defaultHostname do seu gateway em DEFAULT_HOSTNAME, sem o identificador do protocolo. Por exemplo:

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

Acompanhamento da atividade da API

  1. Veja os gráficos de atividade da sua API na página API Gateway na Google Cloud consola. Clique na sua API para ver os respetivos gráficos de atividade na página Vista geral. Os pedidos podem demorar alguns momentos a ser refletidos nos gráficos.

  2. Consulte os registos de pedidos da sua API na página Explorador de registos. Pode encontrar um link para a página do Explorador de registos na página do API Gateway na Google Cloud consola.

    Aceder ao API Gateway

    Depois de aceder à página do API Gateway:

    1. Selecione a API a ver.
    2. Clique no separador Detalhes.
    3. Clique no link em Registos.

Acabou de implementar e testar uma API no API Gateway com gRPC!

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste início rápido, pode:

Em alternativa, também pode eliminar o Google Cloud projeto usado para este tutorial.