Comece a usar os Cloud Endpoints para o ambiente flexível do App Engine com o ESP

Este tutorial mostra como configurar e implementar uma API de exemplo e o Extensible Service Proxy (ESP) executado numa instância no ambiente flexível do App Engine. A API REST do código de exemplo é descrita através da especificação OpenAPI. O tutorial também mostra como criar uma chave da API e usá-la em pedidos à API.

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Obter o exemplo de código

Java

Para clonar ou transferir a API de exemplo:

1. O exemplo de código usa o Maven. Se não tiver o Maven 3.3.9 ou superior, transfira-o e instale-o.
2. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

3. Altere para o diretório que contém o código de exemplo:

   cd java-docs-samples/endpoints/getting-started

Python

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd python-docs-samples/endpoints/getting-started

Ir

Para clonar ou transferir a API de exemplo:

1. Certifique-se de que a GOPATHvariável de ambiente está definida.
2. Clone o repositório da app de exemplo para a sua máquina local:

   go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

3. Altere para o diretório que contém o código de exemplo:

   cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started

PHP

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd php-docs-samples/endpoints/getting-started

Ruby

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd ruby-docs-samples/endpoints/getting-started

NodeJS

Para clonar ou transferir a API de exemplo:

1. Clone o repositório da app de exemplo para a sua máquina local:

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

2. Altere para o diretório que contém o código de exemplo:

   cd nodejs-docs-samples/endpoints/getting-started

Configurar pontos finais

O exemplo de código inclui o ficheiro de configuração da OpenAPI, openapi-appengine.yaml, que se baseia na especificação da OpenAPI v2.0.

Para configurar pontos finais:

1. No diretório de código de exemplo, abra o openapi-appengine.yamlficheiro de configuração.
   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"

   Ir

   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"

   Tenha em conta o seguinte:

   • O exemplo de configuração apresenta as linhas junto ao campo host que tem de modificar. Para implementar openapi-appengine.yaml nos Endpoints, é necessário o documento OpenAPI completo.
   • O exemplo openapi-appengine.yaml contém uma secção para configurar a autenticação que não é necessária para este tutorial. Não tem de configurar as linhas com YOUR-SERVICE-ACCOUNT-EMAIL e YOUR-CLIENT-ID.
   • A OpenAPI é uma especificação independente do idioma. O mesmo ficheiro openapi-appengine.yaml encontra-se no exemplo getting-started no repositório do GitHub de cada idioma para sua conveniência.

2. Na linha com o campo host, substitua YOUR-PROJECT-ID pelo ID do seu Google Cloud projeto. Por exemplo:

   host: "example-project-12345.appspot.com"

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

Para obter informações sobre os campos no documento OpenAPI que o Endpoints requer, consulte o artigo Configurar o Endpoints.

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.

Para implementar a configuração dos Endpoints:

1. Certifique-se de que está no diretório endpoints/getting-started.
2. Carregue a configuração e crie um serviço gerido:

   gcloud endpoints services deploy openapi-appengine.yaml
   

Em seguida, o comando gcloud chama a API Service Management para criar um serviço gerido com o nome que especificou no campo host do ficheiro openapi-appengine.yaml. A gestão de serviços configura o serviço de acordo com as definições no ficheiro openapi-appengine.yaml. Quando faz alterações ao openapi-appengine.yaml, tem de voltar a implementar o ficheiro para atualizar o serviço Endpoints.

À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos no ficheiro openapi-appengine.yaml que não requerem uma chave da API. Quando terminar de configurar o serviço, a gestão de serviços apresenta uma mensagem com o ID de configuração do serviço e o nome do serviço, semelhante ao seguinte:

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 Endpoints. O ID de configuração do serviço consiste numa data/hora seguida de um número de revisão. Se implementar o ficheiro openapi-appengine.yaml novamente no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço. Pode ver a configuração do serviço Endpoints na página Endpoints > Serviços na Google Cloud consola.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração de pontos finais.

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.

Implementar o back-end da API

Até agora, implementou o documento OpenAPI na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como implementar a API de exemplo e o ESP no App Engine.

Para implementar o back-end da API:

1. Adicione o nome do serviço ao ficheiro app.yaml:
   Java

   Abra o ficheiro 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 ficheiro 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

   Ir

   Abra o ficheiro 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 ficheiro 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 ficheiro 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 ficheiro 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 seu serviço Endpoints. Este é o mesmo nome que configurou no campo host do seu documento OpenAPI. Por 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 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.

2. Guarde o ficheiro app.yaml.

Uma vez que a secção endpoints_api_service está incluída no ficheiro app.yaml, o comando gcloud app deploy implementa e configura o ESP num contentor separado do ambiente flexível do App Engine. Todo o tráfego de pedidos é encaminhado através do ESP, e este encaminha pedidos e respostas de e para o contentor que executa o seu código do servidor de back-end.

3. Certifique-se de que está no diretório endpoints/getting-started. É aqui que se encontra o ficheiro de configuração do openapi-appengine.yaml.
4. Execute o seguinte comando para implementar a API de exemplo e o ESP no App Engine:
Java
Implemente através do Maven:
mvn appengine:stage
gcloud app deploy target/appengine-staging
Python
gcloud app deploy
Ir
gcloud app deploy
PHP
gcloud app deploy
Ruby
gcloud app deploy
NodeJS
gcloud app deploy

O comando gcloud app deploy cria um registo de DNS no formato YOUR_PROJECT_ID.appspot.com, que usa quando envia pedidos para a API. Recomendamos que aguarde alguns minutos antes de enviar pedidos à sua API enquanto o App Engine é completamente inicializado.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação flexível do App Engine.

Para mais informações, consulte o artigo Implementar o back-end da API.

Enviar pedidos para a API

Agora que o serviço está a ser executado no App Engine, pode enviar-lhe pedidos.

Crie uma chave da API e defina uma variável de ambiente

O código de exemplo requer uma chave da API. Para simplificar o pedido, defina uma variável de ambiente para a chave da API.

1. No mesmo Google Cloud projeto que usou para a sua API, crie uma chave da API na página de credenciais da API. Se quiser criar uma chave da API num Google Cloud projeto diferente, consulte o artigo Ativar uma API no seu Google Cloud projeto.

   Aceda à página Credenciais

2. Clique em Criar credenciais e, de 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 a atribuir a uma variável de ambiente:
   • No Linux ou macOS: export ENDPOINTS_KEY=AIza...
   • No Windows PowerShell: $Env:ENDPOINTS_KEY="AIza..."

Envie o pedido

Linux ou Mac OS

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

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

2. Envie um pedido HTTP através das variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY que definiu anteriormente:

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

Nos curl anteriores:

• A opção --data especifica os dados a publicar na 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 seu Google Cloud ID do projeto:

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

2. Envie um pedido HTTP através das variáveis de ambiente ENDPOINTS_HOST e ENDPOINTS_KEY que definiu 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 anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

• Selecione POST como verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, introduza o seguinte:
  {"message":"hello world"}
• No URL, use o endereço e a chave da API reais em vez das variáveis de ambiente.appspot.com Por exemplo:
  https://example-project-12345.appspot.com/echo?key=AIza...

A API devolve a mensagem que lhe envia e responde com o seguinte:

{
  "message": "hello world"
}

Se não recebeu 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.

Acompanhamento da atividade da API

1. Veja os gráficos de atividade da sua API na página Endpoints.

   Aceda à página Serviços de pontos finais

   Pode demorar alguns momentos até que o pedido seja refletido nos gráficos.

2. Consulte os registos de pedidos da sua API na página do Explorador de registos.

   Aceda à página do Explorador de registos