Começar a usar os Endpoints para o Compute Engine com o ESP

OpenAPI   |  gRPC

Esta página mostra como implementar um exemplo simples de 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.

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 amostra do GitHub.

Para configurar pontos finais:

1. 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. Este ficheiro define a API do serviço Bookstore.
   2. Crie o seguinte diretório: 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:

      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_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, altere --proto_path para que o compilador pesquise o diretório onde guardou bookstore.proto..proto

2. Crie um ficheiro YAML de configuração da API gRPC:
   1. Guarde uma cópia do api_config.yamlficheiro. Este ficheiro define a configuração da API gRPC para o serviço Bookstore.
   2. Substitua MY_PROJECT_ID no ficheiro api_config.yaml pelo ID do projeto. Google Cloud Por exemplo:

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

      Tenha em atenção que o valor do campo apis.name neste ficheiro corresponde exatamente ao nome da API totalmente qualificado do ficheiro .proto. Caso contrário, a implementação não funciona. O serviço Bookstore está definido em bookstore.proto no pacote endpoints.examples.bookstore. O nome da API totalmente qualificado é endpoints.examples.bookstore.Bookstore, tal como aparece no ficheiro api_config.yaml.

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

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.

1. Certifique-se de que está no diretório onde se encontram os ficheiros api_descriptor.pb e api_config.yaml.
2. 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
   

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

Implementar o back-end da API

Até agora, implementou a configuração da API na gestão de serviços, 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:

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 exemplo e o ESP num contentor do Docker

Para executar o serviço gRPC de exemplo com o ESP 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 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 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:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --http2_port=9000 \
       --backend=grpc://bookstore:8000
   

   A opção --rollout_strategy=managed configura 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.

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

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

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

4. Envie 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.
     

     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!

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.