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.

Objetivos

Use a seguinte lista de tarefas de alto nível à medida que avança no tutorial. Todas as tarefas são necessárias para enviar pedidos com êxito para a API.

1. Configure um Google Cloud projeto. Consulte a secção Antes de começar.
2. Instale o software necessário e crie uma aplicação do App Engine. Consulte o artigo Instalar e configurar o software necessário.
3. Transfira o exemplo de código. Consulte a secção Obter o exemplo de código.
4. Gere um ficheiro de configuração da OpenAPI. Consulte o artigo Configurar o Cloud Endpoints.
5. Implemente a configuração do Endpoints para criar um serviço do Endpoints. Consulte o artigo Implementar a configuração dos Endpoints.
6. Execute o exemplo no seu computador. Veja o artigo Executar o exemplo localmente.
7. Crie um back-end para publicar a API e implemente a API. Consulte o artigo Implementar o back-end da API.
8. Envie um pedido para a API. Consulte o artigo Enviar um pedido para a API.
9. Acompanhe a atividade da API. Consulte o artigo Acompanhamento da atividade da API.
10. Evite incorrer em cobranças na sua conta Google Cloud . Consulte a secção Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Endpoints
• App Engine

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

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. Tome nota do ID do projeto, pois é necessário mais tarde.

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 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 YOUR_REGION pela região onde quer que a aplicação do App Engine seja criada.

      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.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Atenção: a eliminação de um projeto tem os seguintes efeitos:
• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar 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.

O que se segue?

• Saiba mais acerca da arquitetura dos Frameworks de Endpoints.
• Saiba mais sobre as anotações da API disponíveis.
• Saiba como servir a sua API a partir de um caminho diferente.
• Saiba como monitorizar a sua API.
• Saiba como restringir o acesso com chaves de API.
• Saiba como tratar o controlo de versões da API.
• Saiba mais sobre as opções de apoio técnico da comunidade.