Primeiros passos com o Cloud Endpoints Frameworks para Java

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 tem autorização para 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 consulte Como gerenciar a CLI gcloud e configurações personalizadas.

   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.

   Por 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

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.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

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.

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

(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

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

1. Confira os gráficos de atividade da sua API no console do Google Cloud em 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 amostra. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.