Nesta página, você aprende a configurar, implantar e enviar solicitações para uma API de amostra usando o Cloud Endpoints Frameworks para Java. Ele é integrado ao ambiente de execução padrão do App Engine para Java 8. O Endpoints Frameworks consiste em ferramentas, bibliotecas e recursos que permitem gerar APIs e bibliotecas de clientes a partir de um aplicativo do App Engine.
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. Consulte Antes de começar.
- Instale o software necessário e crie um aplicativo do App Engine. Consulte Como instalar e configurar o software necessário.
- Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
- Gere um arquivo de configuração OpenAPI. Consulte Como configurar o Cloud Endpoints.
- Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
- Execute a amostra no seu computador. Consulte Como executar a amostra localmente.
- Crie um back-end para exibir a API e implante-a. 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.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Verifique se a cobrança está ativada para o seu projeto do Google Cloud.
- Anote o código do projeto, ele será necessário mais tarde.
Como instalar e configurar o software necessário
- Se o Java 8 não estiver instalado, faça o download do Java Development Kit (JDK) no site da Oracle (em inglês) e instale-o. Como o Endpoints Frameworks para Java depende do ambiente de execução padrão do App Engine para Java 8, não há suporte para qualquer outra versão do Java.
- Se você não tiver o Maven 3.3.9 ou versões posteriores, faça o download e instale-o.
-
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 e inicialize a CLI do Google Cloud.
- Execute os seguintes comandos:
- Verifique se a gcloud CLI está autorizada a acessar seus dados e serviços no Google Cloud:
gcloud auth login
- Use o Application Default Credentials:
gcloud auth application-default login
- Instale o componente
app-engine-java
do SDK do Google Cloud:gcloud components install app-engine-java
- Atualize para a versão mais recente do SDK Google Cloud e de todos os componentes:
gcloud components update
- Verifique se a gcloud CLI está autorizada a acessar seus dados e serviços no Google Cloud:
- Crie um aplicativo do App Engine:
-
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 do Google Cloud. Se você tiver outros projetos do Google Cloud e quiser usargcloud
consulte Como gerenciar a CLI gcloud e configurações personalizadas. - Selecione a região em que você quer criar o aplicativo do App Engine. Execute o comando abaixo para receber uma lista de regiões:
gcloud app regions list
- Crie um aplicativo do App Engine usando o comando a seguir.
Substitua
YOUR_PROJECT_ID
pelo ID do projeto do Google Cloud eYOUR_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
-
Defina o projeto padrão como o ID do projeto.
Observação para usuários do Windows: se você for instalar o JDK e o Maven no Windows, escolha um diretório para a instalação que não tenha um espaço no caminho. Para saber mais, consulte Maven no Windows.
Como receber o código de exemplo
Para clonar o exemplo de API do GitHub:
Clone o repositório de amostra na sua máquina local:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
Mude para o diretório que contém o código de amostra:
cd java-docs-samples/appengine-java8/endpoints-v2-backend
Como configurar o Endpoints
O código de amostra inclui a ferramenta Endpoints Frameworks que gera um arquivo de configuração OpenAPI que descreve a API REST do código de amostra. Siga as etapas desta seção para configurar e criar o projeto Maven de amostra a fim de gerar o arquivo de configuração OpenAPI.
Adicionar o código do projeto ao código da amostra de API
É necessário adicionar o ID do projeto coletado no momento em que você criou seu projeto ao pom.xml
da amostra antes de implantar o código.
Para adicionar o ID do projeto:
Edite o arquivo
java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml
.Pesquise
<endpoints.project.id>
e substituaYOUR_PROJECT_ID
pelo ID do projeto do Google Cloud.Por exemplo:
<endpoints.project.id>example-project</endpoints.project.id>
Salve as alterações.
Como criar um projeto de amostra
Para criar o projeto:
Verifique se você está no diretório
java-docs-samples/appengine-java8/endpoints-v2-backend
.Execute este comando:
mvn clean package
Espere o projeto ser criado. Quando a operação for concluída, aparecerá uma mensagem semelhante a esta:
[INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 14.846s [INFO] Finished at: Wed April 13 09:43:09 PDT 2016 [INFO] Final Memory: 24M/331M
Como gerar um arquivo de configuração OpenAPI
Use uma ferramenta da biblioteca do Endpoints Frameworks para gerar um documento da OpenAPI chamado openapi.json
. Ele descreve a API REST do código de amostra.
Para gerar o arquivo de configuração OpenAPI:
Invoque a ferramenta do Endpoints Frameworks usando este comando:
mvn endpoints-framework:openApiDocs
Espere as especificações da configuração serem criadas. Quando a operação for concluída, aparecerá uma mensagem semelhante a esta:
OpenAPI document written to target/openapi-docs/openapi.json
Ignore quaisquer mensagens sobre falha de carregamento de uma classe logger estática.
Como implantar a configuração do Endpoints
Para implantar a configuração do Endpoints, use o Service Infrastructure, a plataforma de serviços básicos do Google usada pelo Endpoints Frameworks e outros produtos para a criação e o gerenciamento de APIs e serviços.
Para implantar o arquivo de configuração:
Verifique se você está no diretório
java-docs-samples/appengine-java8/endpoints-v2-backend
.Implante o arquivo de configuração OpenAPI gerado na seção anterior:
gcloud endpoints services deploy target/openapi-docs/openapi.json
Isso cria um novo serviço do Endpoints com o nome no formato YOUR_PROJECT_ID.appspot.com
. Esse nome é configurado em pom.xml
e outros arquivos de configuração incluídos na amostra. Quando você implanta a API no App Engine, um registro DNS é criado usando o formato de nome YOUR_PROJECT_ID.appspot.com
, que é o nome de domínio totalmente qualificado (FQDN, na sigla em inglês) usado ao enviar solicitações para a API.
Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Ignore os avisos sobre os caminhos em openapi.json
que não exigem uma chave de API. Com a conclusão bem-sucedida, uma linha semelhante à seguinte exibe o código de configuração e o nome do serviço:
Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]
No exemplo anterior, 2017-02-13-r2
é o ID de configuração do serviço e example-project-12345.appspot.com
é o nome do serviço.
Consulte gcloud
Endpoints services deploy para mais informações.
Como verificar os serviços obrigatórios
Para fornecer gerenciamento de API, o Endpoints Frameworks requer os seguintes serviços: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.comgcloud 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 o ENDPOINTS_SERVICE_NAME, é possível:
Após 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 camponame
da configuração do gRPC Endpoints.
Para mais informações sobre os comandos gcloud
, consulte serviços gcloud
.
Como executar a amostra no local
Depois de implantar a configuração do Endpoints, execute a amostra localmente.
Crie uma variável de ambiente chamada
ENDPOINTS_SERVICE_NAME
, que é usada no arquivoappengine-web.xml
da amostra para definir o nome do host. A seguir, substituaYOUR_PROJECT_ID
pelo ID do projeto do Google Cloud.No Linux ou Mac OS:
export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
No Windows PowerShell:
$Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
Consiga novas credenciais de usuário que serão usadas no Application Default Credentials:
gcloud auth application-default login
Execute o servidor de desenvolvimento:
mvn appengine:run
A instância local pode ser acessada em
http://localhost:8080
, conforme indicado pelos registros impressos pelo comandomvn appengine:run
:[INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
Envie uma solicitação para a instância local.
Linux ou Mac OS
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
http://localhost:8080/_ah/api/echo/v1/echo
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
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} `
-URI "http://localhost:8080/_ah/api/echo/v1/echo").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 ver informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.
A mensagem enviada é retornada pela API com a seguinte resposta:
{
"message": "hello world"
}
Como implantar o back-end da API
Até agora, você implantou a configuração da OpenAPI no Service Management, mas não o código que exibe o back-end da API. Esta seção mostra como implantar a API de amostra no App Engine.
Para implantar o back-end da API:
Verifique se você está no diretório
java-docs-samples/appengine-java8/endpoints-v2-backend
Implante o código de implementação de API usando o Maven:
mvn appengine:deploy
Na primeira vez que você fizer o upload de um aplicativo de amostra, talvez precise autorizar a implantação. Siga as instruções. Quando uma janela do navegador for exibida com um código, copie-o para a janela do terminal.
Aguarde a conclusão do upload.
Recomendamos que você aguarde alguns minutos até que o App Engine seja inicializado totalmente antes de enviar solicitações à sua API.
Como enviar uma solicitação à API
Após a implantação da API e do arquivo de configuração, é possível enviar solicitações para ela.
Linux ou Mac OS
Envie uma solicitação HTTP usando curl
. Substitua [YOUR_PROJECT_ID]
pelo ID do projeto do Google Cloud.
curl \
--request POST \
--header "Content-Type: application/json" \
--data '{"message":"hello world"}' \
https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo
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
Envie uma solicitação HTTP usando Invoke-WebRequest
. Substitua [YOUR_PROJECT_ID]
pelo ID do projeto do Google Cloud.
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
-Headers @{"content-type"="application/json"} -URI `
"https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").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"}
-
Digite o URL para o aplicativo de amostra. Por exemplo:
https://example-project-12345.appspot.com/_ah/api/echo/v1/echo
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 Frameworks.
Rastrear a atividade da API
Confira os gráficos de atividade da API no console do Google Cloud na página Endpoints > Serviço.
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.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
A seguir
- Saiba mais sobre a arquitetura do Endpoints Frameworks.
- Saiba mais sobre as anotações de API disponíveis.
- Saiba mais sobre como exibir sua API a partir de um caminho diferente.
- Saiba mais sobre como monitorar a API.
- Saiba mais sobre como restringir o acesso com chaves de API.
- Saiba mais sobre como gerenciar o controle de versões da API.
- Saiba mais sobre as opções de suporte da comunidade.