Começar a usar os frameworks do Cloud Endpoints para Java

Esta página mostra como configurar, implementar e enviar pedidos para uma API de exemplo usando os Cloud Endpoints Frameworks para Java. O Endpoints Frameworks for Java está integrado com o ambiente de execução Java 8 padrão do App Engine. O Endpoints Frameworks consiste em ferramentas, bibliotecas e capacidades que lhe permitem gerar APIs e bibliotecas cliente a partir de uma aplicação do App Engine.

Instalar e configurar o software necessário

1. Se não tiver o Java 8 instalado, transfira o Java Development Kit (JDK) a partir do site da Oracle e instale-o. Uma vez que os Endpoints Frameworks for Java dependem do ambiente de execução Java 8 padrão do App Engine, os Endpoints Frameworks não suportam outras versões do Java.
2. Se não tiver o Maven 3.3.9 ou superior, transfira-o e instale-o.

Nota para utilizadores do Windows: se estiver a instalar o JDK e o Maven no Windows, instale-os num diretório que não tenha um espaço no caminho. Consulte o artigo Maven no Windows para mais informações.

3. Precisa de uma aplicação para enviar pedidos para a API de exemplo.

   • Utilizadores do Linux e macOS: este tutorial oferece um exemplo de utilização do curl, que normalmente vem pré-instalado no seu sistema operativo. Se não tiver o curl, pode transferi-lo na curl página de lançamentos e transferências.
   • Utilizadores do Windows: este tutorial fornece um exemplo com Invoke-WebRequest, que é suportado no PowerShell 3.0 e posterior.
4. Transfira e inicialize a CLI do Google Cloud.
5. Execute os seguintes comandos:
   1. Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços em Google Cloud:

      gcloud auth login

   2. Usar credenciais padrão da aplicação:

      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 do Google Cloud e de todos os componentes:

      gcloud components update

6. Crie uma aplicação do App Engine:
   1. Defina o projeto predefinido para o ID do seu projeto.

      gcloud config set project YOUR_PROJECT_ID

      Substitua YOUR_PROJECT_ID pelo ID do seu Google Cloud projeto. Se tiver outros Google Cloud projetos e quiser usar gcloud para os gerir, consulte o artigo Gerir configurações da CLI gcloud.

   2. Selecione a região onde quer criar a sua aplicação do App Engine. Execute o seguinte comando para obter uma lista de regiões:

      gcloud app regions list

   3. Crie uma aplicação do App Engine com o seguinte comando. Substitua YOUR_PROJECT_ID pelo ID do seu projeto e Google Cloud pela região onde quer que a aplicação do App Engine seja criada.YOUR_REGION

      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION

Obter o exemplo de código

Para clonar a API de exemplo do GitHub:

1. Clone o repositório de exemplo para a sua máquina local:

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

2. Altere para o diretório que contém o código de exemplo:

   cd java-docs-samples/appengine-java8/endpoints-v2-backend
   

Configurar pontos finais

O código de exemplo inclui a ferramenta Endpoints Frameworks que gera um ficheiro de configuração OpenAPI que descreve a API REST do código de exemplo. Siga os passos nesta secção para configurar e criar o projeto Maven de exemplo, de modo que possa gerar o ficheiro de configuração da OpenAPI.

Adicionar o ID do projeto ao exemplo de código da API

Tem de adicionar o ID do projeto obtido quando criou o projeto ao pom.xml do exemplo antes de poder implementar o código.

Para adicionar o ID do projeto:

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

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

   Por exemplo:

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

3. Guarde as alterações.

Criar o projeto de exemplo

Para criar o projeto:

1. Certifique-se de que está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Execute o seguinte comando:

   mvn clean package
   

3. Aguarde pela compilação do projeto. Quando o projeto termina com êxito, é apresentada uma mensagem semelhante à seguinte:

   [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
   

Gerar o ficheiro de configuração da OpenAPI

Usa uma ferramenta da biblioteca Endpoints Frameworks para gerar um documento OpenAPI denominado openapi.json. Este ficheiro descreve a API REST do código de exemplo.

Para gerar o ficheiro de configuração da OpenAPI:

1. Invoque a ferramenta Endpoints Frameworks através deste comando:

   mvn endpoints-framework:openApiDocs
   

2. Aguarde pela criação da especificação de configuração. Quando terminar, é apresentado um mensagem semelhante a esta:

   OpenAPI document written to target/openapi-docs/openapi.json
   

   Ignore todas as mensagens sobre a falha ao carregar uma classe de registo estática.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, usa a infraestrutura de serviços, a plataforma de serviços fundamentais da Google, usada pelos Endpoints Frameworks e outros serviços para criar e gerir APIs e serviços

Para implementar o ficheiro de configuração:

1. Certifique-se de que está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Implemente o ficheiro de configuração da OpenAPI gerado na secção anterior:

   gcloud endpoints services deploy target/openapi-docs/openapi.json
   

Esta ação cria um novo serviço de Endpoints com o nome no formato YOUR_PROJECT_ID.appspot.com. Este nome está configurado em pom.xml e noutros ficheiros de configuração incluídos no exemplo. Tenha em atenção que, quando implementa a API no App Engine, é criado um registo de DNS com o formato de nome YOUR_PROJECT_ID.appspot.com, que é o nome do domínio totalmente qualificado (FQDN) que usa quando envia pedidos para a API.

À medida que cria e configura o serviço, a gestão de serviços envia informações para o terminal. Pode ignorar com segurança os avisos sobre os caminhos em openapi.json que não requerem uma chave da API. Após a conclusão bem-sucedida, é apresentada uma linha semelhante à seguinte com o ID de configuração do serviç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 o artigo gcloud Implementação de serviços de pontos finais para mais informações.

A verificar os serviços necessários

Para fornecer a gestão de APIs, o Endpoints Frameworks requer os seguintes serviços:

Nome	Título
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

Na maioria dos casos, o comando gcloud endpoints services deploy ativa estes serviços obrigatórios. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

• Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.

• Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

• Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.

• Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

Para mais informações sobre os comandos gcloud, consulte os serviços gcloud.

Executar o exemplo localmente

Depois de implementar a configuração do Endpoints, pode executar o exemplo localmente.

1. Crie uma variável de ambiente denominada ENDPOINTS_SERVICE_NAME, que é usada no ficheiro appengine-web.xml do exemplo para definir o nome do anfitrião. No exemplo seguinte, substitua YOUR_PROJECT_ID pelo ID do seu projeto.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. Adquira novas credenciais de utilizador para usar com as Credenciais padrão da aplicação:

   gcloud auth application-default login
   

3. Execute o servidor de programação:

   mvn appengine:run
   

   A instância local está acessível em http://localhost:8080, conforme indicado pelos registos impressos pelo comando mvn appengine:run:

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

4. Envie um pedido 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

Nos curl anteriores:

• A opção --data especifica os dados a publicar na 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 anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

A API devolve a mensagem que lhe envia e responde com o seguinte:

{
 "message": "hello world"
}

Implementar o back-end da API

Até agora, implementou a configuração da OpenAPI na gestão de serviços, mas ainda não implementou o código que publica o back-end da API. Esta secção explica como implementar a API de amostra no App Engine.

Para implementar o back-end da API:

1. Certifique-se de que está no diretório java-docs-samples/appengine-java8/endpoints-v2-backend

2. Implemente o código de implementação da API através do Maven:

    mvn appengine:deploy
   

   Quando carregar uma app de exemplo pela primeira vez, pode ser-lhe pedido que autorize a implementação. Siga as instruções. Quando lhe for apresentada uma janela do navegador com um código, copie-o para a janela do terminal.

3. Aguarde que o carregamento termine.

   Recomendamos que aguarde alguns minutos antes de enviar pedidos para a sua API enquanto o App Engine é completamente inicializado.

Enviar um pedido para a API

Depois de implementar a API e o respetivo ficheiro de configuração, pode enviar pedidos para a API.

Linux ou Mac OS

Envie um pedido HTTP através de curl. Substitua [YOUR_PROJECT_ID] pelo seu 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

Nos curl anteriores:

• A opção --data especifica os dados a publicar na API.
• A opção --header especifica que os dados estão no formato JSON.

PowerShell

Envie um pedido HTTP através de Invoke-WebRequest. Substitua [YOUR_PROJECT_ID] pelo ID do seu Google Cloud projeto:

(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 anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar o pedido:

• Selecione POST como verbo HTTP.
• Para o cabeçalho, selecione a chave content-type e o valor application/json.
• Para o corpo, introduza o seguinte:
  {"message":"hello world"}
• Introduza o URL da aplicação de exemplo. Por exemplo:
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

A API devolve a mensagem que lhe envia e responde com o seguinte:

{
 "message": "hello world"
}

Se não recebeu uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API nos Frameworks de Endpoints!

Nota: se quiser partilhar o que gostou neste tutorial, não hesite em enviar feedback na parte inferior desta página. O seu feedback ajuda-nos a melhorar estes tutoriais.
Se recebeu um erro, junte-se ao google-cloud-endpoints grupo Google e diga-nos o que correu mal. Este grupo recebe respostas de outros utilizadores do Endpoints e de engenheiros da Google, que monitorizam o grupo.

Acompanhamento da atividade da API

1. Veja os gráficos de atividade da sua API na Google Cloud consola na página Endpoints > Serviço.

   Aceda à página Serviços de pontos finais

   Pode demorar alguns momentos até que o pedido seja refletido nos gráficos.

2. Consulte os registos de pedidos da sua API na página do Explorador de registos.

   Aceda à página do Explorador de registos

Criar um portal para programadores para a API

Pode usar o portal do Cloud Endpoints para criar um portal do programador, um Website que pode usar para interagir com a API de exemplo. Para saber mais, consulte a vista geral do portal do Cloud Endpoints.