Primeiros passos com o Cloud Endpoints no ambiente flexível do App Engine com ESP

Este tutorial mostra como configurar e implantar uma API de amostra e o Extensible Service Proxy (ESP) em execução em uma instância do ambiente flexível do App Engine. A API REST do código de amostra será descrita com a especificação OpenAPI. Você também verá como criar uma chave de API e usá-la em solicitações para a API.

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

Obter o exemplo de código

Java

Para clonar ou fazer o download da API de amostra:

  1. O código de amostra usa o Maven. Se você não tiver o Maven 3.3.9 ou versões posteriores, faça o download e instale-o.
  2. Clone o repositório do aplicativo de amostra na máquina local: 
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

  3. 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 aplicativo de amostra na máquina local: 
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

  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 -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 aplicativo de amostra na máquina local: 
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

  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 aplicativo de amostra na máquina local: 
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

  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 aplicativo de amostra na máquina local: 
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Como alternativa, faça o download da amostra (em inglês) como um arquivo zip e o descompacte.

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

Como configurar o Endpoints

O código de amostra inclui o arquivo de configuração da OpenAPI, openapi-appengine.yaml, que é baseado na especificação OpenAPI v2.0 (em inglês).

Para configurar o Endpoints:
  1. No diretório de código de amostra, abra o arquivo de configuração openapi-appengine.yaml.

    Java
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Python
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Go
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    PHP
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    Ruby
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"
    NodeJS
    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR-PROJECT-ID.appspot.com"

    Observe o seguinte:

    • A amostra de configuração exibe as linhas próximas ao campo host, que precisa ser modificado. Para implantar openapi-appengine.yaml no Endpoints, é preciso ter o documento completo da OpenAPI.
    • O exemplo openapi-appengine.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-appengine.yaml está na amostra getting-started no repositório do GitHub de cada linguagem.

  2. Na linha com o campo host, substitua YOUR-PROJECT-ID pelo ID do projeto Google Cloud . Exemplo: 
    host: "example-project-12345.appspot.com"

O Endpoints usa o texto configurado no campo host como o nome do serviço. Quando você implanta a API no back-end do App Engine, uma entrada DNS com um nome no formato YOUR-PROJECT-ID.appspot.com é criada automaticamente.

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

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-appengine.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-appengine.yaml. O Service Management configura o serviço de acordo com as configurações no arquivo openapi-appengine.yaml. Ao fazer alterações em openapi-appengine.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-appengine.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 [example-project-12345.appspot.com]

No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço e example-project-12345.appspot.com é 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-appengine.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 Google Cloud console.

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

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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, é possível:

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

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

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

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. Nesta seção, veja como implantar a API de amostra e o ESP no App Engine.

Para implantar o back-end da API:

  1. Adicione seu nome de serviço ao arquivo app.yaml

    Java

    Abra o arquivo endpoints/getting-started/src/main/appengine/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Python

    Abra o arquivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Go

    Abra o arquivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    PHP

    Abra o arquivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
  # previously run the deploy command, you can list your existing configuration
  # ids using the 'configs list' command as follows:
  #
  #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
  #
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Ruby

    Abra o arquivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    NodeJS

    Abra o arquivo endpoints/getting-started/app.yaml.

    endpoints_api_service:
  # The following values are to be replaced by information from the output of
  # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
  name: ENDPOINTS-SERVICE-NAME
  rollout_strategy: managed

    Substitua ENDPOINTS-SERVICE-NAME pelo nome do serviço do Endpoints. Ele é o mesmo que foi configurado no campo host do documento da OpenAPI. Exemplo: 

    endpoints_api_service:
  name: example-project-12345.appspot.com
  rollout_strategy: managed

    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é 5 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.

  2. Salve o arquivo app.yaml.

    3. Como a seção endpoints_api_service está incluída no arquivo app.yaml, o comando gcloud app deploy implanta e configura o ESP em um contêiner separado para o ambiente flexível do App Engine. Todo o tráfego de solicitação é roteado pelo ESP, que atua como proxy em solicitações e respostas de e para o contêiner que executa o código de servidor do back-end.

  3. Verifique se você está no diretório endpoints/getting-started. É aqui que seu arquivo de configuração openapi-appengine.yaml está localizado.
  4. Execute o seguinte comando para implantar a API e o ESP de amostra no App Engine:

    5. Java

    Implante usando o Maven:

    mvn appengine:stage
gcloud app deploy target/appengine-staging
    Python
    gcloud app deploy
    Go
    gcloud app deploy
    PHP
    gcloud app deploy
    Ruby
    gcloud app deploy
    NodeJS
    gcloud app deploy

    O comando gcloud app deploy cria um registro DNS no formato YOUR_PROJECT_ID.appspot.com, usado ao enviar solicitações à API. Recomendamos que você espere alguns minutos antes de enviar solicitações para a API enquanto o Google App Engine é completamente inicializado.

Caso receba uma mensagem de erro, consulte Como solucionar problemas de implantação flexível no App Engine.

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

Como enviar solicitações à API

Agora que o serviço está em execução no App Engine, é possível enviar solicitações para ele.

Crie uma chave de API e defina 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 Google Cloud usado para a API, crie uma chave de API na página de credenciais da API. Se você quiser 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 MACOS

  1. Crie uma variável de ambiente para o URL do projeto do App Engine. Substitua YOUR_PROJECT_ID pelo Google Cloud ID do projeto:

    export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com

  2. Envie uma solicitação HTTP usando as variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY definidas anteriormente:

    curl --request POST \
  --header "content-type:application/json" \
  --data '{"message":"hello world"}' \
  "${ENDPOINTS_HOST}/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

  1. Crie uma variável de ambiente para o URL do projeto do App Engine. Substitua YOUR_PROJECT_ID pelo Google Cloud ID do projeto:

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. Envie uma solicitação HTTP usando as variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY definidas anteriormente:

    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "$Env:ENDPOINTS_HOST/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.

Aplicativo de terceiros

É possível usar um aplicativo de terceiros, como o Postman, uma extensão do navegador Chrome, para enviar a solicitação:

  • 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 o endereço e a chave de API do appspot.com em vez das variáveis de ambiente. Por exemplo:
    https://example-project-12345.appspot.com/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 rastrear atividade da API

  1. Veja os gráficos de atividades da API na página "Endpoints".

    Ir para a página Serviços do Endpoints

    Pode levar alguns instantes para que a solicitação apareça nos gráficos.

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

    Acessar a página Análise de registros