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.
Objetivos
Ao seguir o tutorial, use a lista detalhada de tarefas abaixo. Em todas elas, é necessário que as solicitações para a API sejam enviadas com sucesso.
- Configure um projeto do Google Cloud, instale o software necessário e crie um aplicativo do App Engine. Consulte Antes de começar.
- Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
- Configurar o arquivo
openapi-appengine.yaml
, usado para configurar o Endpoints. Consulte Como configurar o Endpoints. - Implante a configuração do Endpoints para criar um serviço. Consulte Como implantar a configuração do Endpoints.
- Implante a API e o ESP no App Engine: Consulte Como implantar o back-end da API.
- Envie uma solicitação à API. Consulte Como enviar uma solicitação à API.
- Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
- Evite cobranças na sua conta do Google Cloud. Consulte Fazer limpeza.
Custos
Neste documento, você usará 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.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Antes de começar
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Anote o código do projeto, ele será necessário mais tarde.
-
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 tenhacurl
, faça o download na página Versões e downloads (em inglês) docurl
. - 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.
- Usuários de Linux e macOS: este tutorial fornece um exemplo de uso de
- Faça o download da Google Cloud CLI.
-
Atualize a CLI gcloud e instale os componentes do Endpoints.
gcloud components update
-
Verifique se a Google Cloud CLI (
gcloud
) está autorizada a acessar seus dados e serviços no Google Cloud: Na nova guia aberta no navegador, selecione uma conta.gcloud auth login
-
Defina o projeto padrão como o ID do projeto.
gcloud config set project YOUR_PROJECT_ID
Substitua YOUR_PROJECT_ID pela ID do seu projeto. Se você tiver outros projetos do Google Cloud e quiser usar
gcloud
para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud. - Selecione a região em que você quer criar o aplicativo do App Engine. Execute o comando a seguir para visualizar uma lista de regiões:
gcloud app regions list
- Crie um aplicativo do App Engine.
Substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud e YOUR_REGION pela região em que você quer que o aplicativo do App Engine seja criado.
gcloud app create \ --project=YOUR_PROJECT_ID \ --region=YOUR_REGION
Buscar o código de exemplo
Para clonar ou fazer o download da API de amostra:
- 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.
- 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.
- Acesse o diretório que contém o código de amostra:
cd java-docs-samples/endpoints/getting-started
Para clonar ou fazer o download da API de amostra:
- 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.
- Acesse o diretório que contém o código de amostra:
cd python-docs-samples/endpoints/getting-started
Para clonar ou fazer o download da API de amostra:
- Verifique se a variável de ambiente
GOPATH
(em inglês) está configurada. - Clone o repositório do app de amostra na máquina local:
go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
- Acesse o diretório que contém o código de amostra:
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
Para clonar ou fazer o download da API de amostra:
- 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.
- Acesse o diretório que contém o código de amostra:
cd php-docs-samples/endpoints/getting-started
Para clonar ou fazer o download da API de amostra:
- 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.
- Acesse o diretório que contém o código de amostra:
cd ruby-docs-samples/endpoints/getting-started
Para clonar ou fazer o download da API de amostra:
- 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.
- 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).
- No diretório de código de amostra, abra o arquivo de configuração
openapi-appengine.yaml
.Java Python Go PHP Ruby NodeJS Observe o seguinte:
- A amostra de configuração exibe as linhas próximas ao campo
host
, que precisa ser modificado. Para implantaropenapi-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 amostragetting-started
no repositório do GitHub de cada linguagem.
- A amostra de configuração exibe as linhas próximas ao campo
- Na linha com o campo
host
, substitua YOUR-PROJECT-ID pelo ID do projeto do 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:
- Verifique se você está no diretório
endpoints/getting-started
. - 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 conferir a configuração do serviço do Endpoints na página Endpoints > Serviços no console do Google 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 |
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
Ative também seu serviço do Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Para determinar o ENDPOINTS_SERVICE_NAME, é possível:
Após implantar a configuração de 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 camponame
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:
- Adicione seu nome de serviço ao arquivo
app.yaml
Java Abra o arquivo
endpoints/getting-started/src/main/appengine/app.yaml
.Python Abra o arquivo
endpoints/getting-started/app.yaml
.Go Abra o arquivo
endpoints/getting-started/app.yaml
.PHP Abra o arquivo
endpoints/getting-started/app.yaml
.Ruby Abra o arquivo
endpoints/getting-started/app.yaml
.NodeJS Abra o arquivo
endpoints/getting-started/app.yaml
.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 configuração mais recente do serviço implantado. 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. - Salve o arquivo
app.yaml
. - Verifique se você está no diretório
endpoints/getting-started
. É aqui que seu arquivo de configuraçãoopenapi-appengine.yaml
está localizado. - Execute o seguinte comando para implantar a API e o ESP de amostra no App Engine:
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.
Implante usando o Maven:
mvn appengine:stage gcloud app deploy target/appengine-staging
gcloud app deploy
gcloud app deploy
gcloud app deploy
gcloud app deploy
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.
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.
- Clique em Criar credenciais e, em seguida, selecione Chave de API.
- Copie a chave para a área de transferência.
- Clique em Fechar.
- 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..."
- No Linux ou no macOS:
Enviar a solicitação
LINUX OU MACOS
Crie uma variável de ambiente para o URL do projeto do App Engine. Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud:
export ENDPOINTS_HOST=https://YOUR_PROJECT_ID.appspot.com
Envie uma solicitação HTTP usando as variáveis de ambiente
ENDPOINTS_HOST
eENDPOINTS_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
Crie uma variável de ambiente para o URL do projeto do App Engine. Substitua o YOUR_PROJECT_ID pelo ID do projeto do Google Cloud:
$Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"
Envie uma solicitação HTTP usando as variáveis de ambiente
ENDPOINTS_HOST
eENDPOINTS_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 valorapplication/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
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.
Verifique os registros de solicitações da API na página "Visualizador de registros".
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 amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Consulte Como excluir uma API e as instâncias relacionadas para saber como interromper os serviços usados neste tutorial.