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. Para enviar solicitações à API, é necessário concluir todas as tarefas.

  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. 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 tutorial, usamos 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. Novos usuários do Google Cloud podem ser qualificados para uma avaliação gratuita.

Ao concluir este tutorial, exclua os recursos criados para evitar o faturamento contínuo. Para mais informações, consulte Como fazer a limpeza.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

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

    Acessar a página do seletor de projetos

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

  4. 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 (links em inglês).
  3. 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.

  4. 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.
  5. Faça o download e inicialize o SDK do Cloud.
  6. Execute os seguintes comandos:
    1. Verifique se o SDK do Cloud está autorizado 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 do Cloud:
      gcloud components install app-engine-java
    4. Atualize para a versão mais recente do SDK do Cloud e todos os componentes:
      gcloud components update
  7. 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 do SDK do Cloud.

    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

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.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, você pode:

  • Após implantar a configuração do Endpoints, acesse a página Pontos de extremidade 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 sua especificação do OpenAPI. Para gRPC, a ENDPOINTS_SERVICE_NAME é o que você especificou no campo name de sua 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.

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

Como rastrear atividade da API

  1. Veja os gráficos de atividade para sua API no Console do 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 "Logs Viewer"

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 Visão geral do Portal do Cloud Endpoints.

Como fazer a limpeza

Para evitar cobranças na conta do Google Cloud Platform, referentes aos recursos usados neste tutorial:

  1. No Console do Cloud, acesse a página Gerenciar recursos:

    Acessar a página "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