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. Configurar 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 à API. Consulte Como enviar uma solicitação à API.
9. Rastreie a atividade da API. Consulte Como rastrear a atividade da API.
10. Para evitar cobranças na sua conta do Google Cloud . Consulte Limpeza.

Custos

Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:

• Endpoints
• App Engine

Para gerar uma estimativa de custo baseada na sua projeção de uso, use a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste gratuito.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 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 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 Google Cloud . Se você tiver outros projetos do Google Cloud e quiser usar gcloud para gerenciá-los, consulte Como gerenciar as 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

Obter o exemplo de código

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 projetoGoogle 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	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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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:

• 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. No comando a seguir, substitua YOUR_PROJECT_ID pelo ID do projetoGoogle Cloud .

   No Linux ou no 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 Google Cloud ID do projeto:

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 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 valor application/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.

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.

Rastrear a atividade da API

1. Veja 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.

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.

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 atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. 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.