Primeiros passos com o gateway de API e o Cloud Run para gRPC

Nesta página, mostramos como configurar o gateway de API para gerenciar e proteger um serviço de back-end do Cloud Run com gRPC.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para implantar um gateway de API no serviço de back-end do Cloud Run com gRPC.

  1. Criar ou selecionar um projeto do Google Cloud.
  2. Se você não implantou seu próprio Cloud Run, implante um serviço gRPC de back-end de amostra. Consulte a etapa 7 em Antes de começar.
  3. Ative os serviços de gateway de API obrigatórios.
  4. Crie um documento de configuração da API gRPC que descreva sua API e configure as rotas para o Cloud Run. Consulte Como configurar uma configuração de API com gRPC.
  5. Implante um gateway de API com a configuração de API. Consulte Como implantar um gateway de API.
  6. Teste a implantação da API enviando uma solicitação. Consulte Como enviar uma solicitação à API.
  7. Rastreie a atividade para seus serviços. Consulte Como rastrear a atividade da API.
  8. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

  1. No console do Google Cloud, acesse a página Painel e selecione ou crie um projeto do Google Cloud.

    Ir para a página "Painel"

  2. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

  3. Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de PROJECT_ID.

  4. Anote o número do projeto, porque ele será necessário mais tarde. No restante desta página, esse número de projeto é chamado de PROJECT_NUMBER.

  5. Faça o download e instale a Google Cloud CLI.

    Fazer o download da CLI gcloud

  6. Siga as etapas no Guia de início rápido do gRPC para Python (em inglês) para instalar o gRPC e as ferramentas dele.

  7. Implante o serviço de back-end gRPC do Cloud Run de python-grpc-bookstore-server para usar com este tutorial. O serviço gRPC usa a seguinte imagem de contêiner:

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

    Siga as etapas em Início rápido: implantação de um contêiner pré-agrupado de exemplo para implantar o serviço. Substitua a imagem do contêiner especificada nesse início rápido com gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Anote o URL do serviço, a região e o ID do projeto em que o serviço foi implantado.

Como ativar serviços obrigatórios

A API Gateway requer a ativação dos seguintes serviços do Google:

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

Para confirmar que os serviços obrigatórios estão ativados:

gcloud services list

Se você não encontrar 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 do gcloud, consulte serviços gcloud.

Como criar uma configuração de API com gRPC

A amostra bookstore-grpc contém os arquivos necessários para fazer cópias locais e configurações.

  1. Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço .proto:
    1. Salve uma cópia de bookstore.proto do repositório de exemplo no seu diretório de trabalho atual. Esse arquivo define a API do serviço Bookstore.
    2. Crie o seguinte diretório no diretório de trabalho: mkdir generated_pb2
    3. Crie o arquivo de descritor, api_descriptor.pb, usando o compilador de buffers de protocolo protoc. Execute o seguinte comando no diretório onde você salvou 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 ambiente da versão do gRPC, caso você use um diretório diferente para arquivos de entrada .proto, mude --proto_path para que o compilador pesquise o diretório em que salvou bookstore.proto.

  2. Crie um arquivo de texto chamado api_config.yaml no diretório de trabalho atual (o mesmo diretório que contém bookstore.proto). Por conveniência, esta página refere-se ao documento de configuração da API gRPC pelo nome do arquivo, mas você pode nomear algo diferente, se preferir. Adicione o seguinte conteúdo ao arquivo: 
    # 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
    O recuo é importante para o formato yaml. Por exemplo, o campo name deve estar no mesmo nível de type.

  3. No campo name, um serviço chamado *.apigateway.PROJECT_ID.cloud.goog em que PROJECT_ID é o nome do ID do projeto do Google Cloud.

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

    Neste exemplo, presumimos que você esteja usando o serviço de back-end gRPC Bookstore criado em Antes de começar. Se necessário, substitua esse valor pelo URL do serviço Cloud Run.

  5. Salve 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
    em que:
    • CONFIG_ID especifica o nome da configuração da API;
    • API_ID especifica o nome da sua API;
    • PROJECT_ID é o nome do projeto do Google Cloud.
    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

Como implantar um gateway de API

Para implantar a configuração da API gRPC em um 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

onde:

  • GATEWAY_ID especifica o nome do gateway.
  • API_ID especifica o nome da API Gateway associada à API.
  • CONFIG_ID especifica o nome da configuração da API implantada no gateway;

  • GCP_REGION é a região do Google Cloud do gateway implantado.

  • PROJECT_ID é o nome do projeto do Google Cloud.

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, o comando a seguir pode exibir detalhes sobre o gateway:

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

Observe o valor da propriedade defaultHostname na saída deste comando. Esta é a parte do nome do host do URL do gateway que você usará para testar a implantação na próxima etapa.

Exemplo: 

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

Como enviar uma solicitação à API

Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.

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

    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. Instale as dependências:

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

  4. Envie uma solicitação à API de amostra:

    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 de protocolo. Exemplo:

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

Como rastrear a atividade da API

  1. Veja os gráficos de atividade da sua API na página Gateway da API no console do Google Cloud. Clique na sua API para ver os respectivos gráficos de atividade na página Visão geral. Talvez leve alguns instantes para a solicitação aparecer nos gráficos.

  2. Verifique os registros de solicitações da API na página "Visualizador de registros". Há um link para a página Explorador de registros na página Gateway de API no console do Google Cloud.

    Acessar a página "Gateway de API"

    Na página "API Gateway", faça o seguinte

    1. Selecione a API a ser visualizada.
    2. Clique na guia Details.
    3. Clique no link em Registros.

Você acabou de implantar e testar uma API no gateway de API com o gRPC.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, faça o seguinte:

Como alternativa, também é possível excluir o projeto do Google Cloud usado neste tutorial.