Esta página mostra como implementar um exemplo simples de um serviço gRPC com o proxy de serviço extensível (ESP) num contentor Docker no Compute Engine.
Esta página usa a versão Python do exemplo bookstore-grpc. Consulte a secção O que se segue para ver exemplos de gRPC noutros idiomas.
Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.
Objetivos
Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.
- Configure um Google Cloud projeto e transfira o software necessário. Consulte a secção Antes de começar.
- Crie uma instância de VM do Compute Engine. Consulte o artigo Criar uma instância do Compute Engine.
- Copie e configure ficheiros do exemplo
bookstore-grpc. Consulte o artigo Configurar pontos finais. - Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
- Implemente a API e o ESP na VM do Compute Engine. Consulte o artigo Implementar o back-end da API.
- Envie um pedido para a API. Consulte o artigo Enviar um pedido para a API.
- Evite incorrer em cobranças na sua Google Cloud conta. Consulte a secção 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 prevista,
use a calculadora de preços.
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
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Tome nota do ID do projeto, pois é necessário mais tarde.
- Instale e inicialize a CLI Google Cloud.
- Atualize a CLI gcloud e instale os componentes do Endpoints:
gcloud components update
-
Certifique-se de que a CLI do Google Cloud (
gcloud) está autorizada a aceder aos seus dados e serviços no Google Cloud: No novo separador do navegador apresentado, selecione uma conta.gcloud auth login
-
Defina o projeto predefinido para o ID do seu projeto.
gcloud config set project YOUR_PROJECT_ID
Substitua YOUR_PROJECT_ID pelo ID do seu projeto. Se tiver outros Google Cloud projetos e quiser usar o
gcloudpara os gerir, consulte o artigo Gerir configurações da CLI gcloud. - Siga os passos no guia de início rápido do gRPC Python para instalar o gRPC e as ferramentas do gRPC.
Criar uma instância do Compute Engine
- In the Google Cloud console, go to the Create an instance page.
- Na secção Firewall, selecione Permitir tráfego HTTP e permitir tráfego HTTPS.
- Para criar a VM, clique em Criar.
- Certifique-se de que consegue estabelecer ligação à instância de VM.
- In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
- Agora, pode usar o terminal para executar comandos do Linux na sua instância do Debian.
- Introduza
exitpara desassociar da instância.
- Tome nota do nome da instância, da zona e do endereço IP externo, uma vez que são necessários mais tarde.
Para criar uma instância do Compute Engine:

Aguarde algum tempo para que a instância seja iniciada. Quando estiver pronta, é apresentada na página Instâncias de VM com um ícone de estado verde.
Configurar pontos finais
Clone o bookstore-grpcrepositório de exemplo do GitHub.
Para configurar pontos finais:
- Crie um arquivo descritor protobuf autocontido a partir do seu arquivo de serviço
.proto:- Salve uma cópia de
bookstore.protodo repositório de exemplo. Esse arquivo define a API do serviço Bookstore. - Crie o seguinte diretório:
mkdir generated_pb2 - Crie o arquivo de descritor,
api_descriptor.pb, usando o compilador de buffers de protocoloprotoc. Execute o seguinte comando no diretório onde você salvoubookstore.proto:python -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_pathestá 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_pathpara que o compilador pesquise o diretório em que salvoubookstore.proto.
- Salve uma cópia de
- Crie um arquivo YAML de configuração da API gRPC:
- Salve uma cópia do arquivo
api_config.yaml. Esse arquivo define a configuração da API gRPC do serviço Bookstore. - Substitua MY_PROJECT_ID no arquivo
api_config.yamlpelo ID do projeto Google Cloud . Exemplo:# # Name of the service configuration. # name: bookstore.endpoints.example-project-12345.cloud.goog
Observe que o valor do campo
apis.nameneste arquivo corresponde exatamente ao nome da API totalmente qualificado do arquivo.proto; caso contrário, a implantação não funcionará. O serviço Bookstore é definido embookstore.protodentro do pacoteendpoints.examples.bookstore. O nome da API totalmente qualificado éendpoints.examples.bookstore.Bookstore, assim como aparece no arquivoapi_config.yaml.apis: - name: endpoints.examples.bookstore.Bookstore
- Salve uma cópia do arquivo
Consulte o artigo Configurar pontos finais para mais informações.
Implementação da 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.
- 确保您位于
api_descriptor.pb和api_config.yaml文件所在的目录中。 - 确认
gcloud命令行工具当前使用的默认项目是您要向其部署 Endpoints 配置的 Google Cloud 项目。验证从以下命令返回的项目 ID,以确保不会在错误的项目中创建服务。gcloud config list project
如果您需要更改默认项目,请运行以下命令:
gcloud config set project YOUR_PROJECT_ID
- 使用 Google Cloud CLI 部署
proto descriptor文件和配置文件:gcloud endpoints services deploy api_descriptor.pb api_config.yaml
在创建和配置服务时,Service Management 会向终端输出信息。部署完成后,系统将显示如下所示的消息:
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
CONFIG_ID 是部署创建的唯一 Endpoints 服务配置 ID。例如:
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
在前面的示例中,
2017-02-13r0是服务配置 ID,bookstore.endpoints.example-project.cloud.goog是服务名称。服务配置 ID 由日期戳后跟一个修订版本号组成。如果您在同一天再次部署 Endpoints 配置,服务配置 ID 中的修订版本号将递增。
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.comAtive 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 possíveis ENDPOINTS_SERVICE_NAME é apresentada na coluna Nome do serviço.
Para a OpenAPI, ENDPOINTS_SERVICE_NAME é o que especificou no campo
hostda sua especificação OpenAPI. Para o gRPC, ENDPOINTS_SERVICE_NAME é o que especificou no camponameda 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 endpoints.
Consulte o artigo Implementar a configuração dos Endpoints para ver informações adicionais.
Implementar o back-end da API
Até agora, implementou a configuração da API no Service Management, mas ainda não implementou o código que serve o back-end da API. Esta secção explica como configurar o Docker na instância da VM e executar o código de back-end da API e o ESP num contentor Docker.
Instale o Docker na instância de VM
Para instalar o Docker na instância de VM:
- Defina a zona do seu projeto executando o comando:
gcloud config set compute/zone YOUR_INSTANCE_ZONE
Substitua YOUR_INSTANCE_ZONE pela zona onde a sua instância está a ser executada.
- Associe-se à sua instância através do seguinte comando:
gcloud compute ssh INSTANCE_NAME
Substitua INSTANCE_NAME pelo nome da instância de VM.
- Consulte a
documentação do Docker
para configurar o repositório do Docker. Certifique-se de que segue os passos que correspondem à versão e à arquitetura da sua instância de VM:
- Jessie ou mais recente
- x86_64 / amd64
Execute a API de exemplo e o ESP num contentor do Docker
Para executar o serviço gRPC de amostra com o ESP num contentor Docker para que os clientes o possam usar:
- Na instância de VM, crie a sua própria rede de contentores denominada
esp_net.sudo docker network create --driver bridge esp_net
- Execute o servidor Bookstore de exemplo que serve a API de exemplo:
sudo docker run \ --detach \ --name=bookstore \ --net=esp_net \ gcr.io/endpointsv2/python-grpc-bookstore-server:1 - Execute o contentor do Docker do ESP pré-embalado. Nas opções de arranque do ESP, substitua SERVICE_NAME pelo nome do seu serviço. Este é o mesmo nome que configurou no campo
namedo ficheiroapi_config.yaml. Por exemplo:bookstore.endpoints.example-project-12345.cloud.googsudo docker run \ --detach \ --name=esp \ --publish=80:9000 \ --net=esp_net \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --http2_port=9000 \ --backend=grpc://bookstore:8000A opção
--rollout_strategy=managedconfigura o ESP para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, até 5 minutos após implementar uma nova configuração de serviço, o ESP deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de um ID de configuração específico para o ESP usar. Para mais detalhes sobre os argumentos do ESP, consulte as opções de arranque do ESP.
Se tiver a transcodificação ativada, certifique-se de que configura uma porta para tráfego HTTP 1.1 ou SSL.
Se receber uma mensagem de erro, consulte o artigo Resolução de problemas de pontos finais no Compute Engine.
Enviar um pedido para a API
Se estiver a enviar o pedido a partir da mesma instância em que os contentores do Docker estão a ser executados, pode substituir $SERVER_IP por localhost. Caso contrário,
substitua $SERVER_IP pelo IP externo da instância.
Pode encontrar o endereço IP externo executando o seguinte comando:
gcloud compute instances list
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/
Instale dependências:
pip install virtualenvvirtualenv envsource env/bin/activatepython -m pip install -r requirements.txtEnvie um pedido para a API de exemplo:
python bookstore_client.py --host SERVER_IP --port 80
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.
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!
Limpar
Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.
- Elimine a API:
gcloud endpoints services delete SERVICE_NAME
Substitua
SERVICE_NAMEpelo nome do seu serviço. - In the Google Cloud console, go to the VM instances page.
- Select the checkbox for the instance that you want to delete.
- To delete the instance, click More actions, click Delete, and then follow the instructions.