Primeiros passos com o Cloud Endpoints no Compute Engine

Neste tutorial, você verá como configurar e implantar uma API de amostra e o Extensible Service Proxy (ESP) em contêineres pré-criados do Docker (em inglês) no Compute Engine. A API REST do código de amostra é descrita com a especificação OpenAPI. Além disso, você também aprenderá a criar uma chave de API e a usá-la em solicitações à API.

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

Objetivos

Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Para enviar solicitações à API, é necessário concluir todas as tarefas.

  1. Configure um projeto do Google Cloud. Consulte Antes de começar.
  2. Criar uma instância de VM do Compute Engine. Consulte Como criar uma instância do Compute Engine.
  3. Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
  4. Configurar o arquivo openapi.yaml, usado para configurar o Endpoints. Consulte Como configurar o Endpoints.
  5. Implantar a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
  6. Implantar a API e o ESP na VM do Compute Engine. Consulte Como implantar o back-end da API.
  7. Enviar uma solicitação à API usando um endereço IP. Consulte Como enviar uma solicitação usando um endereço IP.
  8. Configurar um registro DNS para a API. Consulte Como configurar o DNS para o Endpoints.
  9. Enviar uma solicitação à API usando o nome de domínio totalmente qualificado. Consulte Como enviar uma solicitação usando o FQDN.
  10. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
  11. Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.

Custos

Neste tutorial, usamos 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 este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Antes de começar

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

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

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

  4. Anote o ID do projeto, ele será necessário mais tarde.
  5. Você precisará que um aplicativo envie solicitações à API de amostra.

    • Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de curl, que normalmente vem pré-instalado em seu sistema operacional. Caso não tenha curl, faça o download na página Versões e downloads (em inglês) do curl.
    • Usuários do Windows: neste tutorial, há um exemplo que usa Invoke-WebRequest (em inglês), que é compatível com o PowerShell 3.0 e versões posteriores.
  6. Faça o download do SDK do Cloud.
  7. Update the Cloud SDK and install the Endpoints components.
    gcloud components update
  8. Verifique se o SDK do Cloud (gcloud) está autorizado a acessar seus dados e serviços no Google Cloud:
    gcloud auth login
    Na nova guia aberta no navegador, selecione uma conta.
  9. Defina o projeto padrão como o ID do projeto.
    gcloud config set project YOUR_PROJECT_ID

    Substitua YOUR_PROJECT_ID pelo ID do projeto. Se você tiver outros projetos do Google Cloud e quiser usar a gcloud para gerenciá-los, consulte Como gerenciar configurações do SDK do Cloud.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Como criar uma instância do Compute Engine

    Para criar uma instância do Compute Engine:

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

    Acessar a página Instâncias de VM (em inglês)

  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áquina virtual, clique em SSH na linha da instância à qual 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 fazer o download do código de amostra

Faça o download do código de amostra para a máquina local.

Java

Para clonar ou fazer o download da API de amostra:

  1. Clone o repositório do app de amostra na máquina local:
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-la.

  2. Acesse o diretório que contém o código de amostra:
    cd java-docs-samples/endpoints/getting-started
Python

Para clonar ou fazer o download da API de amostra:

  1. Clone o repositório do app de amostra na máquina local:
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-la.

  2. Acesse o diretório que contém o código de amostra:
    cd python-docs-samples/endpoints/getting-started
Go

Para clonar ou fazer o download da API de amostra:

  1. Verifique se a variável de ambiente GOPATH (em inglês) está configurada.
  2. Clone o repositório do app de amostra na máquina local:
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Acesse o diretório que contém o código de amostra:
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

Para clonar ou fazer o download da API de amostra:

  1. Clone o repositório do app de amostra na máquina local:
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-la.

  2. Acesse o diretório que contém o código de amostra:
    cd php-docs-samples/endpoints/getting-started
Ruby

Para clonar ou fazer o download da API de amostra:

  1. Clone o repositório do app de amostra na máquina local:
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-la.

  2. Acesse o diretório que contém o código de amostra:
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

Para clonar ou fazer o download da API de amostra:

  1. Clone o repositório do app de amostra na máquina local:
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Outra opção é fazer o download da amostra como um arquivo zip e extraí-la.

  2. Acesse o diretório que contém o código de amostra:
    cd nodejs-docs-samples/endpoints/getting-started

Configurar o Endpoints

O código de amostra inclui o arquivo de configuração da OpenAPI, openapi.yaml, que é baseado na especificação OpenAPI v2.0 (em inglês). Configure e implante openapi.yaml na máquina local.

Para configurar o Endpoints:

  1. No diretório de código de amostra, abra o arquivo de configuração openapi.yaml.

    Observações:

    • A amostra de configuração exibe as linhas próximas ao campo host, que precisa ser modificado. Para implantar o arquivo openapi.yaml no Endpoints, é necessário o documento completo da OpenAPI.
    • O arquivo de exemplo openapi.yaml contém uma seção para configurar a autenticação que não é necessária para este tutorial. Não é necessário configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
    • A OpenAPI é uma especificação agnóstica de linguagem. Por conveniência, o mesmo arquivo openapi.yaml está na amostra getting-started no repositório do GitHub de cada linguagem.
  2. No campo host, substitua o texto pelo nome do serviço do Endpoints, que precisa estar no seguinte formato:
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    

    Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Exemplo:

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    

Observe que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog é o nome do serviço do Endpoints. e não o nome de domínio totalmente qualificado (FQDN, na sigla em inglês) usado para enviar solicitações à API.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.

Depois de concluir todas as etapas de configuração a seguir para enviar solicitações à API de amostra usando um endereço IP, consulte Como configurar o DNS do Endpoints para informações sobre como configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog para ser o FQDN.

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.

Para implantar a configuração do Endpoints:

  1. Verifique se você está no diretório endpoints/getting-started.
  2. Faça upload da configuração e crie um serviço gerenciado:
    gcloud endpoints services deploy openapi.yaml
    

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerenciado com o nome especificado no campo host do arquivo openapi.yaml. O Service Management configura o serviço de acordo com as configurações no arquivo openapi.yaml. Ao fazer alterações em openapi.yaml, é necessário reimplantar o arquivo para atualizar o serviço do Endpoints.

Durante a criação e a configuração do serviço, a Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos no arquivo openapi.yaml que não exigem uma chave de API. Quando a configuração do serviço é concluída, o Service Management mostra uma mensagem com o código de configuração e o nome do serviço:

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

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e echo-api.endpoints.example-project-12345.cloud.goog é o serviço do Endpoints. 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 o arquivo openapi.yaml novamente no mesmo dia, o número de revisão será incrementado no ID de configuração do serviço. Você pode ver a configuração do serviço do Endpoints na página Endpoints > Serviços no Console do Cloud.

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

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 ENDPOINTS_SERVICE_NAME, você pode:

  • Após implantar a configuração do Endpoints, acesse a página Pontos de extremidade no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

  • Para OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da sua especificação do OpenAPI. Para gRPC, a ENDPOINTS_SERVICE_NAME é o que você especificou no campo name de sua configuração do gRPC Endpoints.

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

Como implantar o back-end da API

Até agora, você implantou o documento da OpenAPI 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. Execute o comando a seguir para definir a zona do projeto:
    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 (em inglês) para configurar o repositório do Docker. Siga os passos que correspondem à versão e à arquitetura da instância da VM:
    • Jessie ou mais recente
    • x86_64/amd64

Executar a API e o ESP em um contêiner do Docker

O ESP é um proxy com base em nginx que se encontra na frente do código de back-end. Ele processa o tráfego de entrada para fornecer a autenticação, o gerenciamento da chave de API, a geração de registros e outros recursos de gerenciamento da API Endpoints.

Para instalar e executar a API de amostra e o ESP em um contêiner do Docker:

  1. Crie uma rede de contêineres própria denominada esp_net.
    sudo docker network create --driver bridge esp_net
    
  2. Execute o servidor de eco que veicula a API de amostra:
    Java
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-java:1.0
    
    Python
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-python:1.0
    
    Go
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-go:1.0
    
    PHP
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-php:1.0
    
    Ruby
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-ruby:1.0
    
    NodeJS
    sudo docker run --detach --name=echo --net=esp_net gcr.io/google-samples/echo-node:1.0
    
  3. Execute o contêiner público predefinido do Docker do ESP. Nas opções de inicialização do ESP, substitua SERVICE_NAME pelo nome do serviço. Ele é o mesmo que foi configurado no campo host do documento da OpenAPI.
    sudo docker run \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --rollout_strategy=managed \
        --backend=echo:8080
    

    A opção --rollout_strategy=managed configura o ESP para usar a implantação mais recente da configuração do serviço. Quando você especifica essa opção, até cinco minutos depois de implantar uma nova configuração de serviço, o ESP detecta a alteração e começa a usá-la automaticamente. Recomendamos especificar essa opção em vez de um ID de configuração específico para uso do ESP. Para mais informações sobre as opções de ESP usadas acima, consulte Opções de inicialização do ESP.

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

Para mais informações, consulte Como implantar o back-end da API.

Como enviar uma solicitação usando um endereço IP

Depois que a API de amostra e o ESP estiverem em execução na instância do Compute Engine, será possível enviar solicitações para a API a partir da máquina local.

Criar uma chave de API e definir uma variável de ambiente

O código de amostra requer uma chave de API. Para simplificar a solicitação, defina uma variável de ambiente para a chave da API.

  1. No mesmo projeto do Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quer criar uma chave de API em um projeto diferente do Google Cloud, consulte Como ativar uma API no projeto do Google Cloud.

    Acessar a página Credenciais

  2. Clique em Criar credenciais e, em seguida, selecione Chave de API.
  3. Copie a chave para a área de transferência.
  4. Clique em Fechar.
  5. No computador local, cole a chave da API para atribuí-la a uma variável de ambiente:
    • No Linux ou no macOS: export ENDPOINTS_KEY=AIza...
    • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Enviar a solicitação

Linux ou mac OS

Utilize curl para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da instância.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

No curl anterior:

  • A opção --data especifica os dados a serem enviados para a API.
  • A opção --header especifica que os dados estão no formato JSON.

PowerShell

Utilize Invoke-WebRequest para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_KEY definida anteriormente. Substitua IP_ADDRESS pelo endereço IP externo da instância.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

No exemplo acima, as duas primeiras linhas terminam em um acento grave. Quando você colar o exemplo no PowerShell, verifique se não há espaço após os acentos graves. Para informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest (em inglês) na documentação da Microsoft.

App de terceiros

É possível usar um aplicativo terceirizado para enviar a solicitação, como o Postman (em inglês), uma extensão do navegador Chrome:

  • Selecione POST como o verbo HTTP.
  • Para o cabeçalho, selecione a chave content-type e o valor application/json.
  • Para o corpo, digite isto:
    {"message":"hello world"}
  • No URL, use a chave de API real em vez da variável de ambiente. Por exemplo:
    http://192.0.2.0:80/echo?key=AIza...

A mensagem enviada é retornada pela API com a seguinte resposta:

{
  "message": "hello world"
}

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.

Como configurar o DNS para o Endpoints

Como o nome do serviço do Endpoints para a API está no domínio .endpoints.YOUR_PROJECT_ID.cloud.goog, é possível usá-lo como o nome de domínio totalmente qualificado (FQDN, na sigla em inglês). Basta fazer uma pequena alteração na configuração do arquivo openapi.yaml. Dessa forma, é possível enviar solicitações para a API de amostra usando echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog em vez do endereço IP.

Para configurar o DNS para o Endpoints:

  1. Abra o arquivo de configuração da OpenAPI, openapi.yaml, e adicione a propriedade x-google-endpoints no nível superior do arquivo (não recuado ou aninhado), como mostrado no snippet a seguir:
        host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
        x-google-endpoints:
        - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
          target: "IP_ADDRESS"
    
  2. Na propriedade name, substitua YOUR_PROJECT_ID pelo ID do projeto.
  3. Na propriedade target, substitua IP_ADDRESS pelo endereço IP usado ao enviar uma solicitação para a API de amostra.
  4. Implante o arquivo de configuração da OpenAPI atualizado na Service Management usando o seguinte comando:
        gcloud endpoints services deploy openapi.yaml
    

Por exemplo, suponha que o arquivo openapi.yaml esteja configurado desta forma:

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.example-project-12345.cloud.goog"
      target: "192.0.2.1"

Ao implantar o arquivo openapi.yaml usando o comando gcloud anterior, o Service Management cria um registro A DNS, echo-api.endpoints.my-project-id.cloud.goog, que é resolvido para o endereço IP de destino, 192.0.2.1. Pode levar alguns minutos para a nova configuração do DNS se propagar.

Configurar o SSL

Para mais detalhes sobre como configurar o DNS e o SSL, consulte Como ativar o SSL para o Endpoints.

Como enviar uma solicitação usando o FQDN

Agora que você tem o registro DNS configurado para a API de amostra, envie uma solicitação usando o FQDN (substitua YOUR_PROJECT_ID pelo ID do projeto) e a variável de ambiente ENDPOINTS_KEY definida anteriormente:
  • No Linux ou no mac OS:
            curl --request POST \
                --header "content-type:application/json" \
                --data '{"message":"hello world"}' \
                "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • No Windows PowerShell:
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

Como rastrear atividade da API

Para rastrear a atividade da API:

  1. Veja os gráficos de atividade da API na página Endpoints > Serviços.

    Ir para a página "Serviços" do Endpoints

    }
    Pode levar alguns instantes até a solicitação aparecer nos gráficos.

  2. Verifique os registros de solicitações da API na página "Logs Viewer".

    Acessar a página "Logs Viewer"

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 para interagir com a API de exemplo. Para saber mais, consulte Visão geral do Portal do Cloud Endpoints.

Como fazer a limpeza

Para evitar cobranças dos recursos usados neste tutorial na sua conta do Google Cloud Platform:

  1. Exclua a API:
    gcloud endpoints services delete SERVICE_NAME
    

    Substitua SERVICE_NAME pelo nome do serviço.

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

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

  3. Marque a caixa de seleção da a instância que você quer excluir.
  4. Clique em Excluir para excluir a instância.

A seguir