Esta página foi traduzida pela API Cloud Translation.

Configure o gRPC do Cloud Endpoints para o Cloud Run com o ESPv2

OpenAPI | gRPC

Esta página mostra como configurar o Cloud Endpoints para o Cloud Run com um back-end gRPC. Os Endpoints usam o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gestão de APIs para o Cloud Run, implemente o contentor ESPv2 pré-criado no Cloud Run. Em seguida, ajuda a proteger os seus serviços através do Cloud Run IAM para que o ESPv2 os possa invocar.

Com esta configuração, o ESPv2 interceta todos os pedidos aos seus serviços e realiza todas as verificações necessárias (como a autenticação) antes de invocar o serviço. Quando o serviço responde, o ESPv2 recolhe e comunica a telemetria, conforme mostrado na figura abaixo. Pode ver as métricas do seu serviço na página Endpoints > Serviços na Google Cloud consola.

Arquitetura de endpoints

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Migrar para o ESPv2

As versões anteriores do Cloud Endpoints não suportavam gRPC no Cloud Run com o ESP. Para usar esta funcionalidade, migre para o proxy de serviço extensível V2.

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para concluir este tutorial.

Crie um Google Cloud projeto e, se ainda não tiver implementado o seu próprio Cloud Run, implemente um serviço gRPC de back-end de exemplo. Consulte a secção Antes de começar.
Reserve um nome do anfitrião do Cloud Run para o serviço ESPv2. Consulte o artigo Reserve um nome do anfitrião do Cloud Run.
Crie um documento de configuração da API gRPC que descreva a sua API e configure as rotas para o Cloud Run. Consulte o artigo Configurar pontos finais.
Implemente o documento de configuração da API gRPC para criar um serviço gerido. Consulte o artigo Implementar a configuração dos Endpoints.
Crie uma nova imagem Docker do ESPv2 com a configuração do serviço dos Endpoints. Consulte o artigo Criar uma nova imagem do ESPv2.
Implemente o contentor do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 a autorização da gestão de identidade e de acesso (IAM) para invocar o seu serviço. Consulte o artigo Implementar o contentor do ESPv2.
Invocar um serviço. Consulte o artigo Enviar um pedido para a API.
Monitorize a atividade nos seus serviços. Consulte o artigo Acompanhamento da atividade da API.
Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Para configurar:

Na Google Cloud consola, aceda à página Gerir recursos e crie um projeto.
Aceda à página Gerir recursos
Certifique-se de que a faturação está ativada para o seu projeto.
Saiba como ativar a faturação
Tome nota do ID do projeto, pois é necessário mais tarde. No resto desta página, este ID do projeto é designado como ESPv2_PROJECT_ID.
Tome nota do número do projeto porque é necessário mais tarde. No resto desta página, este número do projeto é denominado ESPv2_PROJECT_NUMBER.
Transfira e instale a Google Cloud CLI.
Transfira a CLI gcloud
Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas gRPC.
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 da região e do ID do projeto onde o seu serviço está implementado. No resto desta página, este ID do projeto é designado por BACKEND_PROJECT_ID. O nome do serviço do Cloud Run implementado é denominado BACKEND_SERVICE_NAME. O respetivo nome do anfitrião do Cloud Run é denominado BACKEND_HOST_NAME.

Reservar um nome de anfitrião do Cloud Run

Tem de reservar um nome de anfitrião do Cloud Run para o serviço ESPv2 para configurar o documento OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do anfitrião, implementa um contentor de exemplo no Cloud Run. Posteriormente, implementa o contentor do ESPv2 no mesmo serviço do Cloud Run.

Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços.
1. Inicie sessão.
```
gcloud auth login
```
2. No novo separador do navegador apresentado, escolha uma conta que tenha a função de Editor ou Proprietário no Google Cloud projeto que criou para implementar o ESPv2 no Cloud Run.

Defina a região.

gcloud config set run/region us-central1

Implemente a imagem de exemplo gcr.io/cloudrun/hello no Cloud Run. Substitua ESPv2_CLOUD_RUN_SERVICE_NAME pelo nome que quer usar para o serviço.

gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESPv2_PROJECT_ID

Após a conclusão com êxito, o comando apresenta uma mensagem semelhante à seguinte:

Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Por exemplo, se definir ESPv2_CLOUD_RUN_SERVICE_NAME como gateway:

Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

Neste exemplo, https://gateway-12345-uc.a.run.app é o CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app é o v2_CLOUD_RUN_HOSTNAME.

Tome nota de ESPv2_CLOUD_RUN_SERVICE_NAME e ESPv2_CLOUD_RUN_HOSTNAME. Posteriormente, implementa o ESPv2 no serviço do ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. Especifica ESPv2_CLOUD_RUN_HOSTNAME no campo host do seu documento OpenAPI.

Configurar pontos finais

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

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.

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: CLOUD_RUN_HOSTNAME
title: Cloud Endpoints + 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://BACKEND_HOST_NAME

A indentação é importante para o formato YAML. Por exemplo, o campo name tem de estar ao mesmo nível que type.

No campo name, especifique CLOUD_RUN_HOSTNAME, a parte do nome de anfitrião do URL que foi reservada acima em Reservar um nome de anfitrião do Cloud Run. Não inclua o identificador do protocolo, como https:// ou grpcs://.
No campo address na secção backend.rules, substitua BACKEND_HOST_NAME pelo serviço Cloud Run gRPC Bookstore real criado em Antes de começar.

Nota: para usar o gRPC com TLS no Cloud Run, o campo address tem de ter o esquema grpcs:// em vez de https://.
Tome nota do valor da propriedade title no ficheiro api_config.yaml:
```
title: Cloud Endpoints + Cloud Run gRPC
```
O valor da propriedade title torna-se o nome do serviço Endpoints depois de implementar a configuração.
Guarde o documento de configuração da API gRPC.

Consulte o artigo Configurar pontos finais para mais informações.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

Certifique-se de que está no diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.
Confirme que o projeto predefinido que a ferramenta de linha de comandos gcloud está a usar atualmente é o projeto Google Cloud no qual quer implementar a configuração do Endpoints. Valide o ID do projeto devolvido pelo seguinte comando para se certificar de que o serviço não é criado no projeto errado.
```
gcloud config list project
```
Se precisar de alterar o projeto predefinido, execute o seguinte comando:
```
gcloud config set project YOUR_PROJECT_ID
```
Implemente o ficheiro proto descriptor e o ficheiro de configuração através da CLI do Google Cloud:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por exemplo:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e bookstore.endpoints.example-project.cloud.goog é o nome do serviço. O ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar novamente a configuração dos Endpoints no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço.

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:

Nome	Título
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

Na maioria dos casos, o comando gcloud endpoints services deploy ativa estes serviços obrigatórios. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.
Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando 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 servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

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

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais.

Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.

Criar uma nova imagem do ESPv2

Crie a configuração do serviço Endpoints numa nova imagem do Docker do ESPv2. Posteriormente, vai implementar esta imagem no serviço do Cloud Run reservado.

Nota:

Este passo é obrigatório.

A configuração do serviço tem de ser incorporada numa nova imagem do Docker porque o Cloud Run é um serviço de dimensionamento para zero. Isto significa que, quando não existe tráfego, todas as instâncias são eliminadas. Quando o tráfego aumenta, são criadas novas instâncias a pedido. Este tipo de criação de instâncias de serviço também é denominado início a frio. Consulte a documentação sobre a concorrência do Cloud Run para mais informações.

Se a imagem do Docker não tivesse a configuração do serviço incorporada, o Cloud Run teria de fazer duas chamadas API para o Google ServiceManagement no arranque a frio. Estas chamadas são contabilizadas na sua quota da API Google ServiceManagement.

Ao incorporar a configuração do serviço na imagem Docker do ESPv2, remove as duas chamadas API e evita afetar a contagem de quotas do serviço Google ServiceManagement. Este passo também acelera a criação da nova instância do serviço e reduz a latência dos pedidos que aguardam a nova instância.

Tem de executar novamente todo este passo e reimplementar o novo contentor:

Sempre que modifica e reimplementa a configuração do serviço Endpoints. Caso contrário, as alterações à configuração do serviço não são propagadas para o ESPv2.
Quando é lançada uma nova versão do ESPv2. Caso contrário, a versão mais antiga do ESPv2 permanece implementada.

Para criar a configuração do serviço numa nova imagem Docker do ESPv2:

Transfira este script para a sua máquina local onde a CLI gcloud está instalada.

Nota:
Este script requer o bash. Se não estiver a usar o macOS/Linux, pode executá-lo no Cloud Shell, Compute Engine ou subsistema Windows para Linux.
Execute o script com o seguinte comando:
```
chmod +x gcloud_build_image

./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESPv2_PROJECT_ID
```
Nota:
Este script foi concebido para criar uma pasta no diretório /tmp. Certifique-se de que tem acesso de escrita ao diretório /tmp quando executar este script.

Se o acesso de escrita não estiver disponível para o diretório /tmp, tem de modificar o script para especificar um diretório alternativo onde tenha o acesso necessário para criar pastas.

Para ESPv2_CLOUD_RUN_HOSTNAME, especifique o nome do anfitrião do URL que reservou acima em Reservar um nome do anfitrião do Cloud Run. Não inclua o identificador de protocolo, https://.

Por exemplo:
```
chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id
```
O script usa o comando gcloud para transferir a configuração do serviço, criar a configuração do serviço numa nova imagem do ESPv2 e carregar a nova imagem para o registo de contentores do seu projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada por ESPv2_VERSION no nome da imagem de saída. A imagem de saída é carregada para:
```
gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Por exemplo:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Nota:
Transmita a flag -z ao script para gerar a imagem numa localização do registo diferente.

Por exemplo, para enviar a imagem ESPv2 gerada para um centro de dados da União Europeia, transmita -z eu ao script.

Implementar o contentor do ESPv2

Implemente o serviço do Cloud Run do ESPv2 com a nova imagem criada acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome do serviço do Cloud Run que usou quando reservou originalmente o nome do anfitrião acima em Reservar um nome do anfitrião do Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID
```
Nota:
Se o seu serviço gRPC usar qualquer protocolo de streaming, adicione a flag --use-http2 ao comando gcloud run deploy. Atualmente, esta flag só é suportada em gcloud beta run. Adicione esta flag quando implementar o ESPv2 e os serviços do Cloud Run de back-end gRPC.
Se quiser configurar os Endpoints para usar opções de inicialização do ESPv2 adicionais, como ativar o CORS, pode transmitir os argumentos na variável de ambiente ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESPv2_PROJECT_ID
```
Para mais informações e exemplos sobre a definição da variável de ambiente ESPv2_ARGS, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte o artigo Flags do proxy de serviço extensível V2.
Conceda autorização ao ESPv2 para invocar os seus serviços do Cloud Run. Execute o seguinte comando para cada serviço. No seguinte comando:
Nota:
Este passo não é necessário se o serviço do Cloud Run do ESPv2 for implementado sem usar a flag --service-account e o serviço de back-end BACKEND_SERVICE_NAME for implementado no projeto ESPv2_PROJECT_NUMBER.
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está a ser invocado. Se estiver a usar o serviço criado através da implementação de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, use python-grpc-bookstore-server como este valor.
- Substitua ESPv2_PROJECT_NUMBER pelo número do projeto que criou para o ESPv2. Uma forma de encontrar esta informação é aceder à página IAM na consola e encontrar a conta de serviço de computação predefinida, que é a conta de serviço usada na flag `member`. Google Cloud
```
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID
```

Para mais informações, consulte o artigo Gerir o acesso através da IAM.

Enviar pedidos para a API

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

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

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

Altere o diretório de trabalho:

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

Instalar dependências:

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

Envie um pedido para a API de exemplo:
```
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
```
Especifique o nome do anfitrião do seu serviço do Cloud Run do ESPv2 em CLOUD_RUN_HOSTNAME, sem o identificador do protocolo. Por exemplo:
```
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
```
- Consulte os gráficos de atividade da sua API na página Endpoints > Serviços.
  
  Aceda à página Serviços de pontos finais
  
  Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
- Consulte os registos de pedidos da sua API na página do Explorador de registos.
  
  Aceda à página do Explorador de registos

Se não receber uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Acompanhamento da atividade da API

Veja os gráficos de atividade da sua API na página Endpoints > Service na Google Cloud consola.

Veja gráficos de atividade de pontos finais

Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
Consulte os registos de pedidos da sua API na página do explorador de registos.

Veja os registos de pedidos de pontos finais

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

Consulte o artigo Eliminar uma API e instâncias de API para obter informações sobre como parar os serviços usados por este tutorial.