Primeiros passos com o gRPC no Compute Engine

Nesta página, você aprende a implantar um exemplo de serviço gRPC simples com o Extensible Service Proxy (ESP) em um contêiner do Docker no Compute Engine.

A versão Python da amostra do bookstore-grpc é a utilizada nesta página. Consulte as amostras de gRPC em outras linguagens na seção A seguir.

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

Lista de tarefas

Use a lista de tarefas detalhada abaixo enquanto segue o tutorial. A todas elas é exigido que as solicitações para a API sejam enviadas com sucesso.

  1. Configure um projeto do Google Cloud Platform (GCP) e faça o download do software necessário. Consulte Antes de começar.
  2. Crie uma instância de VM do Compute Engine. Consulte Como criar uma instância do Compute Engine.
  3. Copie e configure arquivos da amostra do bookstore-grpc. Consulte Como configurar o Endpoints.
  4. Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
  5. Implante a API e o ESP na VM do Compute Engine. Consulte Como implantar o back-end da API.
  6. Envie uma solicitação à API. Consulte Como enviar uma solicitação à API.
  7. Evite cobranças na sua conta do GCP. Consulte Limpar.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do Google Cloud Platform.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado no projeto do Google Cloud Platform.

    Saiba como ativar o faturamento

  4. Anote o código do projeto, ele será necessário mais tarde.
  5. Instale e inicialize o SDK do Cloud.
  6. Atualize o SDK do Cloud e instale os componentes do Endpoints:
    gcloud components update
  7. Verifique se o SDK do Cloud (gcloud) tem autorização para acessar seus dados e serviços no GCP:
    gcloud auth login
    Na nova guia do navegador que é aberta, escolha uma conta.
  8. Defina o projeto padrão como o código do projeto.
    gcloud config set project YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo código do projeto. Se você tiver outros projetos do GCP e quiser usar o gcloud para gerenciá-los, consulte Como gerenciar configurações do SDK do Cloud.

  9. Siga as etapas no Guia de início rápido do gRPC em Python para instalar o gRPC e as ferramentas dele.

Como criar uma instância do Compute Engine

    Para criar uma instância do Compute Engine:

  1. No Console do GCP, acesse a página "Instâncias de VM".

    Acessar a página "Instâncias da VM"

  2. Clique em Criar instância.
  3. Na seção Firewall, selecione Permitir tráfego HTTP e Permitir tráfego HTTPS.
  4. Clique em Criar para criar a instância.
  5. Captura de tela da janela de criação da instância de VM com as opções necessárias definidas

    Aguarde a inicialização da instância. Quando estiver pronta, ela aparecerá na página **Instâncias de VMs** com um ícone de status verde.

  6. Verifique se você consegue se conectar à instância da VM.
    1. Na lista de instâncias de máquinas virtuais, clique em SSH na linha da instância com que você quer se conectar.
    2. Agora é possível usar o terminal para executar comandos do Linux na instância do Debian.
    3. Digite exit para se desconectar da instância.
  7. Anote o nome, a zona e o endereço IP externo da instância, eles serão necessários mais tarde.

Como configurar o Endpoints

Clone o repositório de amostra do bookstore-grpc do GitHub.

Para configurar o "Endpoints":

  1. Crie um arquivo descritor protobuf autocontido a partir do seu aquivo de serviço .proto:
    1. Salve uma cópia de bookstore.proto a partir do repositório de exemplo. Esse arquivo define a API do serviço Bookstore.
    2. Crie o seguinte diretório: mkdir generated_pb2
    3. Crie um arquivo descritor, api_descriptor.pb, usando o compilador de buffers de protocolo, protoc: Execute o seguinte comando no diretório em que você salvou 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 acima, --proto_path está definido para o diretório de trabalho atual. No seu ambiente de compilação gRPC, caso use um diretório diferente para arquivos de entrada .proto, mude --proto_path para que o compilador pesquise no diretório em que você salvou bookstore.proto.

  2. Crie um arquivo YAML de configuração da API gRPC:
    1. Salve uma cópia do arquivo api_config.yaml. Esse arquivo define a configuração da API gRPC do serviço Bookstore.
    2. Substitua <MY_PROJECT_ID> no seu arquivo api_config.yaml pelo seu código do projeto do GCP. Por exemplo:
      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      O valor do campo apis.name nesse 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 está definido em bookstore.proto dentro do pacote endpoints.examples.bookstore. O nome da API totalmente qualificado será endpoints.examples.bookstore.Bookstore, exatamente como aparece no arquivo api_config.yaml.

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

Para saber mais, consulte Como configurar o Endpoints.

Como implantar a configuração do Endpoints

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

  1. Certifique-se de que você está no diretório onde os arquivos api_descriptor.pb e api_config.yaml estão localizados.
  2. Confirme se o projeto padrão usado atualmente pela ferramenta de linha de comando gcloud é o projeto do GCP em que você quer implantar a configuração do Endpoints. Valide o código do projeto retornado do comando a seguir para garantir que o serviço não seja criado no projeto incorreto.
    gcloud config list project
    

    Se você precisar alterar o projeto padrão, execute o comando:

    gcloud config set project YOUR_PROJECT_ID
    
  3. Implante os arquivos de proto descriptor e de configuração usando a ferramenta de linha de comando gcloud:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a configuração do serviço é concluída, o Service Management envia o código de configuração e o nome do serviço, semelhante ao seguinte:

    Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
    

    No exemplo acima, 2017-02-13r0 é o código de configuração do serviço, e bookstore.endpoints.example-project.cloud.goog é o nome do serviço. O código de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar novamente a configuração do Endpoints no mesmo dia, o número de revisão será alterado no código da configuração do serviço.

Se 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 implantar o back-end da API

Até agora, você implantou a configuração da API no Service Management, mas não o código que exibe o back-end da API. Esta seção contém orientações para configurar o Docker na instância de VM e executar o código de back-end da API e o ESP em um contêiner do Docker.

Instalar o Docker na instância de VM

Para instalar o Docker na instância de VM, faça o seguinte:

  1. Defina a zona do projeto executando o seguinte comando:
    gcloud config set compute/zone YOUR_INSTANCE_ZONE
    

    Substitua YOUR_INSTANCE_ZONE pela zona em que a instância está em execução.

  2. Conecte-se à instância usando o 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. Siga as etapas que correspondem à versão e à arquitetura da instância da VM:
    • Jessie ou mais recente
    • x86_64/amd64

Como executar a API de amostra e o ESP em um contêiner do Docker

Para executar o serviço gRPC de amostra com ESP em um contêiner do Docker para uso dos clientes, faça o seguinte:

  1. Na instância da VM, crie a própria rede de contêineres chamada esp_net.
    sudo docker network create --driver bridge esp_net
    
  2. Execute o servidor do Bookstore de amostra que fornece a API de amostra:
    sudo docker run \
        --detach \
        --name=bookstore \
        --net=esp_net \
        gcr.io/endpointsv2/python-grpc-bookstore-server:1
    
  3. Execute o contêiner predefinido do Docker ESP. Nas opções de inicialização do ESP, substitua SERVICE_NAME pelo nome do serviço. Esse é o mesmo nome configurado no campo name do arquivo 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 mais recente configuração de serviço implantada. Quando essa opção é especificada, a alteração é detectada pelo ESP até um minuto após a implantação de uma nova configuração de serviço e começa a ser usada automaticamente. Recomendamos especificar essa opção em vez de um código de configuração específico para uso do ESP. Para mais detalhes sobre os argumentos do ESP, consulte Opções de inicialização do ESP.

Se a transcodificação estiver ativada, configure uma porta para HTTP1.1 ou tráfego SSL.

Caso você receba uma mensagem de erro, consulte Como solucionar problemas do Cloud Endpoints no Compute Engine.

Como enviar uma solicitação à API

Caso a solicitação seja enviada a partir da mesma instância em que estão sendo executados os contêineres do Docker, substitua $SERVER_IP pelo localhost. Caso contrário, substitua $SERVER_IP pelo IP externo da instância.

Para encontrar o endereço IP externo, execute:

gcloud compute instances list

Para enviar solicitações à API de amostra, use um cliente gRPC de amostra escrito em Python.

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

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

    pip install virtualenv
    virtualenv env
    source env/bin/activate
    python -m pip install -r requirements.txt
    
  4. Envie uma solicitação à API de amostra:

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

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 Cloud Endpoints.

Limpar

Para evitar cobranças na sua conta do GCP pelo uso de recursos neste guia de início rápido:

  1. Exclua a API:
    gcloud endpoints services delete [SERVICE_NAME]
    

    Substitua SERVICE_NAME pelo nome do serviço.

  2. No Console do GCP, acesse a página "Instâncias de VM".

    Acessar a página "Instâncias de VMs"

  3. Clique na caixa de seleção ao lado da da instância que deseja excluir.
  4. Clique no botão Excluir na parte superior da página para excluir a instância.

A seguir

  • Descubra como configurar a API do gRPC do Cloud Endpoints.
  • Consulte a amostra do Bookstore no GitHub para saber mais. Tanto o cliente quanto o servidor estão disponíveis em Python e Java.
  • A amostra do getting-started-grpc está disponível no GitHub nas seguintes linguagens:
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.