Introdução aos Endpoints for Compute Engine com o ESPv2

OpenAPI   |  gRPC

Este tutorial mostra como implementar um exemplo simples de serviço gRPC com o Extensible Service Proxy V2 (ESPv2) num contentor Docker no Compute Engine.

Este tutorial 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.

1. Configure um Google Cloud projeto e transfira o software necessário. Consulte a secção Antes de começar.
2. Crie uma instância de VM do Compute Engine. Consulte o artigo Criar uma instância do Compute Engine.
3. Copie e configure ficheiros do exemplo bookstore-grpc. Consulte o artigo Configurar pontos finais.
4. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
5. Implemente a API e o ESPv2 na VM do Compute Engine. Consulte o artigo Implementar o back-end da API.
6. Envie um pedido para a API. Consulte o artigo Enviar um pedido para a API.
7. 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:

• Compute Engine
• Endpoints

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

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

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

1. 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 the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Tome nota do ID do projeto, pois é necessário mais tarde.
4. Instale e inicialize a CLI Google Cloud.
5. Atualize a CLI gcloud e instale os componentes do Endpoints:

   gcloud components update

6. Certifique-se de que a CLI do Google Cloud (gcloud) está autorizada a aceder aos seus dados e serviços no Google Cloud:

   gcloud auth login

   No novo separador do navegador apresentado, selecione uma conta.
7. 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 gcloud para os gerir, consulte o artigo Gerir configurações da CLI gcloud.

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

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.

Criar uma instância do Compute Engine

Para criar uma instância do Compute Engine:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. Na secção Firewall, selecione Permitir tráfego HTTP e permitir tráfego HTTPS.
3. Para criar a VM, clique em Criar.



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.

4. Certifique-se de que consegue estabelecer ligação à instância de VM.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Agora, pode usar o terminal para executar comandos do Linux na sua instância do Debian.
   3. Introduza exit para desassociar da instância.
5. Tome nota do nome da instância, da zona e do endereço IP externo, uma vez que são necessários mais tarde.

Configurar pontos finais

Clone o bookstore-grpcrepositório de exemplo do GitHub.

Para configurar pontos finais:

1. 通过服务 .proto 文件创建一个独立的 protobuf 描述符文件：
   1. 保存示例代码库中 bookstore.proto 的副本。此文件用于定义 Bookstore 服务的 API。
   2. 创建以下目录：mkdir generated_pb2
   3. 使用 protoc Protocol Buffers 编译器创建描述符文件 api_descriptor.pb。在您保存了 bookstore.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

      在前面的命令中，--proto_path 设置为当前工作目录。在 gRPC 编译环境中，如果对 .proto 输入文件使用其他目录，请更改 --proto_path，以便编译器搜索您保存了 bookstore.proto 文件的目录。

2. 创建 gRPC API 配置 YAML 文件：
   1. 保存 api_config.yaml 文件的副本。此文件用于定义 Bookstore 服务的 gRPC API 配置。
   2. 将 api_config.yaml 文件中的 MY_PROJECT_ID 替换为您的 Google Cloud 项目 ID。例如：

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      请注意，此文件中 apis.name 字段的值应该与 .proto 文件中的完全限定 API 名称完全匹配；否则部署将无法正常运行。Bookstore 服务是在 endpoints.examples.bookstore 包内的 bookstore.proto 中定义的。其完全限定的 API 名称为 endpoints.examples.bookstore.Bookstore，与其在 api_config.yaml 文件中的名称相同。

      apis:
        - name: endpoints.examples.bookstore.Bookstore

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.

1. 确保您位于 api_descriptor.pb 和 api_config.yaml 文件所在的目录中。
2. 确认 gcloud 命令行工具当前使用的默认项目是您要向其部署 Endpoints 配置的 Google Cloud 项目。验证从以下命令返回的项目 ID，以确保不会在错误的项目中创建服务。

   gcloud config list project
   

   如果您需要更改默认项目，请运行以下命令：

   gcloud config set project YOUR_PROJECT_ID
   

3. 使用 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.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 possíveis ENDPOINTS_SERVICE_NAME é apresentada na coluna Nome do serviço.

• Para a OpenAPI, ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, 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 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 ESPv2 num contentor Docker.

Instale o Docker na instância de VM

Para instalar o Docker na instância de VM:

1. 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.

2. 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.

3. 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 amostra e o ESPv2 num contentor do Docker

Para executar o serviço gRPC de exemplo com o ESPv2 num contentor Docker para que os clientes o possam usar:

1. Na instância de VM, crie a sua própria rede de contentores denominada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. 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
   

3. Execute o contentor do Docker do ESPv2 pré-embalado. Nas opções de inicialização do ESPv2, substitua SERVICE_NAME pelo nome do seu serviço. Este é o mesmo nome que configurou no campo name do ficheiro api_config.yaml. Por exemplo: bookstore.endpoints.example-project-12345.cloud.goog

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:2 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --listener_port=9000 \
       --backend=grpc://bookstore:8000
   

   A opção --rollout_strategy=managed configura o ESPv2 para usar a configuração do serviço implementada mais recente. Quando especifica esta opção, no prazo de um minuto após implementar uma nova configuração de serviço, o ESPv2 deteta a alteração e começa a usá-la automaticamente. Recomendamos que especifique esta opção em vez de fornecer um ID de configuração específico para o ESPv2 usar. Para mais detalhes sobre os argumentos do ESPv2, consulte as opções de arranque do ESPv2.

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

要向示例 API 发送请求，您可以使用以 Python 编写的示例 gRPC 客户端。

1. 克隆托管 gRPC 客户端代码的 Git 代码库：

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

2. 切换您的工作目录：

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

3. 安装依赖项：

   pip install virtualenv
   virtualenv env
   source env/bin/activate
   python -m pip install -r requirements.txt

4. 向示例 API 发送一个请求：

   python bookstore_client.py --host SERVER_IP --port 80
   

   • 在 Endpoints > 服务页面中查看 API 的活动图表。
     

     转到“Endpoints 服务”页面

     请求可能需要一些时间才能体现在图表中。

   • 在“日志浏览器”页面中查看 API 的请求日志。
     

     前往 Logs Explorer 页面

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!

Nota: se quiser partilhar o que gostou neste tutorial, não hesite em enviar feedback na parte inferior desta página. O seu feedback ajuda-nos a melhorar estes tutoriais.
Se recebeu um erro, junte-se ao google-cloud-endpoints grupo Google e diga-nos o que correu mal. Este grupo recebe respostas de outros utilizadores do Endpoints e de engenheiros da Google, que monitorizam o grupo.

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.

1. Elimine a API:

   gcloud endpoints services delete SERVICE_NAME

   Substitua SERVICE_NAME pelo nome do seu serviço.

2. In the Google Cloud console, go to the VM instances page.

   Go to VM instances

3. Select the checkbox for the instance that you want to delete.
4. To delete the instance, click More actions, click Delete, and then follow the instructions.

O que se segue?

• Saiba como configurar a sua própria API gRPC para Endpoints.
• Analise o exemplo da livraria no GitHub mais detalhadamente. O cliente e o servidor estão disponíveis em Python e Java.
• A amostra getting-started-grpc está disponível no GitHub nos seguintes idiomas:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js