Primeiros passos com o Cloud Endpoints Frameworks para Java

---

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.

1. Configure um projeto do Google Cloud. Consulte Antes de começar.
2. Instale o software necessário e crie um aplicativo do App Engine. Consulte Como instalar e configurar o software necessário.
3. Faça o download do código de amostra. Consulte Como conseguir o código de amostra.
4. Gere um arquivo de configuração OpenAPI. Consulte Como configurar o Cloud Endpoints.
5. Implante a configuração do Endpoints para criar um serviço dele. Consulte Como implantar a configuração do Endpoints.
6. Execute a amostra no seu computador. Consulte Como executar a amostra localmente.
7. Crie um back-end para exibir a API e implante-a. Consulte Como implantar o back-end da API.
8. Envie uma solicitação para a API. Consulte Como enviar uma solicitação para a API.
9. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
10. 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:

• Endpoints
• App Engine

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 as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

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

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

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

4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Anote o código do projeto, ele será necessário mais tarde.

Como instalar e configurar o software necessário

1. 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.
2. Se você não tiver o Maven 3.3.9 ou versões posteriores, faça o download e instale-o.

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.

3. 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.
4. Faça o download e inicialize a Google Cloud CLI.
5. Execute os seguintes comandos:
   1. Verifique se a CLI gcloud está autorizada a acessar seus dados e serviços no Google Cloud:

      gcloud auth login

   2. Use o Application Default Credentials:

      gcloud auth application-default login

   3. Instale o componente app-engine-java do SDK Google Cloud:

      gcloud components install app-engine-java

   4. Atualize para a versão mais recente do SDK Google Cloud e de todos os componentes:

      gcloud components update

6. Crie um aplicativo do App Engine:
   1. 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 usar gcloud para gerenciá-los, consulte Como gerenciar configurações da CLI gcloud.

   2. 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

   3. Crie um aplicativo do App Engine usando o comando a seguir. 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
      

Como receber o código de exemplo

Para clonar o exemplo de API do GitHub:

1. Clone o repositório de amostra na sua máquina local:

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

2. 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:

1. Edite o arquivo java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

2. Pesquise <endpoints.project.id> e substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud.

   Exemplo:

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. Salve as alterações.

Como criar um projeto de amostra

Para criar o projeto:

1. Verifique se você está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Execute este comando:

   mvn clean package
   

3. 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:

1. Invoque a ferramenta do Endpoints Frameworks usando este comando:

   mvn endpoints-framework:openApiDocs
   

2. 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:

1. Verifique se você está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend.

2. 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 gcloudEndpoints 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	Cargo
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 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.

Como executar a amostra no local

Depois de implantar a configuração do Endpoints, execute a amostra localmente.

1. Crie uma variável de ambiente chamada ENDPOINTS_SERVICE_NAME, que é usada no arquivo appengine-web.xml da amostra para definir o nome do host. A seguir, substitua YOUR_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"
   

2. Consiga novas credenciais de usuário que serão usadas no Application Default Credentials:

   gcloud auth application-default login
   

3. 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 comando mvn appengine:run:

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. 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:

1. Verifique se você está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend

2. 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.

3. 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 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 o seguinte:
  {"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.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Como rastrear a atividade da API

1. Veja os gráficos de atividade da sua 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.

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

   Acessar a página Explorador 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 exemplo. 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.

Cuidado: excluir um projeto tem os seguintes efeitos:
• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.
1. No Console do Google Cloud, acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

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.