Esta página foi traduzida pela API Cloud Translation.

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

OpenAPI | gRPC

Esta página mostra como configurar o Cloud Endpoints para Cloud Run com um back-end de gRPC. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Implante o contêiner ESPv2 pré-construído no Cloud Run para fornecer gerenciamento de API para o Cloud Run. Em seguida, ajude a proteger seus serviços usando o IAM do Cloud Run para que o ESPv2 possa invocá-los.

Com essa configuração, o ESPv2 intercepta todas as solicitações e executa as verificações necessárias, como a autenticação, antes de invocar o serviço. Quando o serviço responde, o ESPv2 coleta e relata a telemetria, como mostrado na figura abaixo. É possível conferir as métricas do serviço na página Endpoints > Serviços no Console do Google Cloud.

Arquitetura do Endpoints

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Como migrar para o ESPv2

As versões anteriores do Cloud Endpoints não eram compatíveis com o gRPC no Cloud Run com ESP. Para usar este recurso, migre para o Extensible Service Proxy V2.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para concluir este tutorial.

Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Run, implante um serviço gRPC de back-end de amostra. Consulte Antes de começar.
Reserve um nome de host do Cloud Run para o serviço ESPv2. Consulte Como reservar um nome de host do Cloud Run.
Crie um documento de configuração da API gRPC que descreva sua API e configure as rotas para o Cloud Run. Consulte Como configurar o Endpoints.
Implante o documento de configuração da API gRPC para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
Crie uma nova imagem do Docker do ESPv2 com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2.
Implante o contêiner do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 a permissão de Gerenciamento de identidade e acesso (IAM, na sigla em inglês) para invocar seu serviço. Consulte Como implantar o contêiner do ESPv2.
Chamar um serviço. Consulte Como enviar uma solicitação à API.
Rastreie a atividade para seus serviços. Consulte Como rastrear a atividade da API.
Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Para configurar:

No console do Google Cloud, acesse a página Gerenciar recursos. e criar um projeto.
Acessar a página Gerenciar recursos
Verifique se o faturamento foi ativado para o projeto.
Saiba como ativar o faturamento
Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de ESP_PROJECT_ID.
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 ESP_PROJECT_NUMBER.
Faça o download e instale a CLI do Google Cloud.
Fazer o download da CLI gcloud
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.
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

Observe a região e o código do projeto em que o serviço foi implantado. No restante desta página, esse ID de projeto é chamado de BACKEND_PROJECT_ID. O nome do serviço Cloud Run implantado é chamado de BACKEND_SERVICE_NAME. O nome do host do Cloud Run é chamado de BACKEND_HOST_NAME.

Como reservar um nome de host do Cloud Run

É preciso reservar um nome do host do Cloud Run para o serviço ESPv2 para configurar o documento da OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do host, você implantará um contêiner de amostra no Cloud Run. Posteriormente, você implantará o contêiner do ESPv2 no mesmo serviço do Cloud Run.

Verifique se a gcloud CLI está autorizada a acessar seus dados e serviços.
1. Faça login.
```
gcloud auth login
```
2. Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 no Cloud Run.

Defina a região.

gcloud config set run/region us-central1

Implantar a imagem de amostra gcr.io/cloudrun/hello no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.

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

Após a conclusão, o comando exibirá uma mensagem semelhante à seguinte:

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

Por exemplo, se você definir CLOUD_RUN_SERVICE_NAME para 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 CLOUD_RUN_HOSTNAME.

Anote CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. Depois, implante o ESPv2 no serviço CLOUD_RUN_SERVICE_NAME do Cloud Run. Especifique CLOUD_RUN_HOSTNAME no campo host do documento da OpenAPI.

Como configurar o Endpoints

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

Create a self-contained protobuf descriptor file from your service .proto file:
1. Save a copy of bookstore.proto from the example repository to your current working directory. This file defines the Bookstore service's API.
2. Create the following directory under your working directory: mkdir generated_pb2
3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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
```
  In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

Create a text file called api_config.yaml in your current working directory (the same directory that contains bookstore.proto). For convenience, this page refers to the gRPC API configuration document by that file name, but you can name it something else if you prefer. Add the following contents to the 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: 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

Indentation is important for yaml format. For example the name field must be at the same level as type.

In the name field, specify CLOUD_RUN_HOSTNAME, the hostname portion of the URL that was reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, such as https:// or grpcs://.
In the address field in the backend.rules section, replace BACKEND_HOST_NAME with the actual gRPC Bookstore Cloud Run service created in Before you begin.

Note: To use gRPC with TLS on Cloud Run, the address field must have the scheme grpcs:// instead of https://.
Note the value of the title property in the api_config.yaml file:
```
title: Cloud Endpoints + Cloud Run gRPC
```
The value of the title property becomes the name of the Endpoints service after you deploy the configuration.
Save your gRPC API configuration document.

Para saber mais, consulte Como configurar o Endpoints.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.
```
gcloud config list project
```
If you need to change the default project, run the following command:
```
gcloud config set project YOUR_PROJECT_ID
```
Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

Como verificar os serviços obrigatórios

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:

Nome	Título
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control
`endpoints.googleapis.com`	Google Cloud Endpoints

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

Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.
Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.

Use o seguinte comando para confirmar se os serviços necessários estão ativados:

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

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

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

Após implantar a configuração do Endpoints, acesse a página Endpoints no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo name da configuração do gRPC Endpoints.

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

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Para mais informações, consulte Como implantar a configuração do Endpoints.

Como criar uma nova imagem do ESPv2

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2. Em seguida, você implantará essa imagem no serviço reservado do Cloud Run.

Observação:

Esta etapa é obrigatória.

A configuração do serviço precisa ser integrada a uma nova imagem docker porque o Cloud Run é um serviço de escalonamento para zero. Isso significa que, quando não houver tráfego, todas as instâncias serão excluídas. Quando o tráfego aumenta, novas instâncias são criadas sob demanda. Esse tipo de criação de instância de serviço também é chamado de inicialização a frio. Consulte a documentação sobre simultaneidade do Cloud Run para saber mais.

Se a imagem do Docker não tivesse a configuração de serviço integrada, o Cloud Run precisaria fazer duas chamadas de API ao Google ServiceManagement na inicialização a frio. Essas chamadas são descontadas da sua cota da API Google ServiceManagement.

Ao criar a configuração do serviço na imagem docker do ESPv2, você remove as duas chamadas de API e evita impactar a contagem da cota do serviço Google ServiceManagement Essa etapa também acelera a criação da nova instância de serviço e reduz a latência das solicitações aguardando a nova instância.

Execute esta etapa inteira novamente e reimplante o novo contêiner:

Todas as vezes que você modificar e reimplantar a configuração do serviço do Endpoints. Caso contrário, as alterações na configuração do serviço não serão propagadas para o ESPv2.
Quando uma nova versão do ESPv2 for lançada. Caso contrário, a versão mais antiga do ESPv2 permanecerá implantada.

Para criar a configuração do serviço em uma nova imagem docker do ESPv2:

Faça o download deste script em sua máquina local em que a gcloud CLI está instalada.

Observação:
Esse script requer bash. Se você não estiver usando o macOS/Linux poderá executá-lo no Cloud Shell, no Compute Engine ou no subsistema do Windows para Linux.

Execute o script com o seguinte comando:

chmod +x gcloud_build_image

./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESP_PROJECT_ID

Para CLOUD_RUN_HOSTNAME, especifique o nome do host do URL que você reservou acima em Como reservar um nome de host 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 da gcloud para fazer o download da configuração do serviço, criar essa configuração em uma nova imagem do ESPv2 e fazer upload da nova imagem para o registro de contêiner do projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada pela ESP_VERSION no nome da imagem de saída. O upload da imagem de saída é feito para:
```
gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Exemplo:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Observação:
Transmita a sinalização -z para o script gerar a imagem em um local de registro diferente.

Por exemplo, para enviar a imagem gerada do ESPv2 para um data center da União Europeia, transmita -z eu para o script.

Como implantar o contêiner do ESPv2

Implante o serviço do Cloud Run do ESPv2 com a nova imagem que você criou acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando reservou originalmente o nome do host acima em Como reservar um nome de host do Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESP_PROJECT_ID
```
Observação:
Se o serviço gRPC usar qualquer protocolo de streaming, adicione a sinalização --use-http2 ao comando gcloud run deploy. Atualmente, esta sinalização só é suportada por gcloud beta run. Adicione essa sinalização ao implantar o ESPv2 e os serviços de back-end do Cloud Run do gRPC.
Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2, como a de ativar o CORS, passe os argumentos na variável de ambiente ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESP_PROJECT_ID
```
Para mais informações e exemplos sobre como configurar a 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 Sinalizações do Extensible Service Proxy V2.
Conceda permissão ao ESPv2 para invocar os serviços do Cloud Run. Execute o seguinte comando para cada serviço. No seguinte comando:
Observação:
Esta etapa não será necessária se o serviço ESPv2 do Cloud Run for implantado sem usar a sinalização --service-account e o serviço de back-end BACKEND_SERVICE_NAME for implantado no projeto ESP_PROJECT_NUMBER.
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está sendo invocado. Se você estiver usando o serviço criado pela implantação de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, use python-grpc-bookstore-server como este valor.
- Substitua ESP_PROJECT_NUMBER pelo número do projeto criado para o ESPv2. Uma forma de descobrir isso é acessar IAM no console do Google Cloud e encontre o Conta de serviço padrão do Compute, que é a conta de serviço usada no a sinalização `member`.
```
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID
```

Para mais informações, consulte Como gerenciar o acesso usando o IAM.

Como enviar solicitações à API

To send requests to the sample API, you can use a sample gRPC client written in Python.

Clone the git repo where the gRPC client code is hosted:

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

Change your working directory:

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

Install dependencies:

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

Send a request to the sample API:
```
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
```
Specify the hostname of your ESPv2 Cloud Run service in CLOUD_RUN_HOSTNAME, without the protocol identifier. For example:
```
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
```
- Look at the activity graphs for your API in the Endpoints > Services page.
  
  Go to the Endpoints Services page
  
  It may take a few moments for the request to be reflected in the graphs.
- Look at the request logs for your API in the Logs Explorer page.
  
  Go to the Logs Explorer page

Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Rastrear a atividade da API

Confira os gráficos de atividade da API na página Endpoints > Serviço no console do Google Cloud.

Ver gráficos de atividades do Endpoints

Pode levar alguns instantes até a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Visualizador de registros".

Ver registros de solicitações do Endpoints

Como criar um portal do desenvolvedor para a API

É possível usar o Portal do Cloud Endpoints para criar um portal do desenvolvedor, um site que você pode usar para interagir com a API de amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.

Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.