Implemente uma API gerida pelo Cloud Endpoints

Iniciar o Cloud Shell

1. Na Google Cloud consola, certifique-se de que está no projeto que quer usar para a API de exemplo.

2. Abra o Cloud Shell.

   Abra o Cloud Shell

   É aberta uma sessão do Cloud Shell num novo frame na parte inferior da Google Cloud consola e é apresentado um comando. A sessão pode demorar alguns segundos a ser inicializada.

   

3. Se estiver a usar um projeto existente, certifique-se de que tem a versão mais recente de todos os componentes gcloud instalados:

   gcloud components update
   

Obter o exemplo de código

1. No Cloud Shell, introduza o seguinte comando para obter a API de exemplo e os scripts:

   git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
   

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

   cd endpoints-quickstart
   

Implementar a configuração dos pontos finais

Para publicar uma API REST nos Endpoints, é necessário um ficheiro de configuração OpenAPI que descreva a API. A API de exemplo inclui um ficheiro OpenAPI pré-configurado denominado openapi.yaml.

Os pontos finais usam a gestão de serviços, um serviço de infraestrutura da Google Cloud para criar e gerir APIs e serviços. Para usar os Endpoints para gerir uma API, implementa o ficheiro de configuração OpenAPI da API na gestão de serviços.

Para implementar a configuração dos Endpoints:

1. No Cloud Shell, no diretório endpoints-quickstart, introduza o seguinte:

   cd scripts
   

2. Execute o seguinte script, que está incluído no exemplo:

   ./deploy_api.sh
   

Os Endpoints usam o campo host no ficheiro de configuração OpenAPI para identificar o serviço. O script deploy_api.sh define o ID do seu projetoGoogle Cloud como parte do nome configurado no campo host. Quando prepara um ficheiro de configuração da OpenAPI para o seu próprio serviço, tem de o fazer manualmente.

Em seguida, o script implementa a configuração da OpenAPI no Service Management através do comando: gcloud endpoints services deploy openapi.yaml

À medida que cria e configura o serviço, o Service Management envia informações para a Google Cloud consola. Pode ignorar com segurança os avisos sobre os caminhos em openapi.yaml que não requerem uma chave da API. Após a conclusão com êxito, é apresentada uma linha semelhante à seguinte que apresenta o ID da configuração do serviço e o nome do serviço:

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

Ativar serviços necessários

No mínimo, os Endpoints requerem que os seguintes serviços Google estejam ativados:

Na maioria dos casos, a implementação da configuração dos Endpoints ativa estes serviços obrigatórios.

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 YOUR-PROJECT-ID.appspot.com

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

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 para publicar o back-end da API. O script incluído no exemplo cria um ambiente flexível do App Engine para alojar o back-end da API e, em seguida, implementa a API no App Engine.deploy_app.sh

Para implementar o back-end da API:

• No Cloud Shell, no diretório endpoints-quickstart/scripts, execute o seguinte script:

  ./deploy_app.sh
  

O script executa o seguinte comando para criar um ambiente flexível do App Engine na região us-central: gcloud app create --region="$REGION"

A criação do back-end do ambiente flexível do App Engine demora vários minutos. Depois de criar a aplicação, o resultado é:

Success! The app is now created.

Em seguida, o script executa o comando gcloud app deploy para implementar a API de exemplo no App Engine.

O resultado é:

Deploying ../app/app_template.yaml...You are about to deploy the following services:

A implementação da API no App Engine demora vários minutos. Quando a API é implementada com êxito no App Engine, o resultado é:

Deployed service [default] to [https://example-project.appspot.com]

Enviar pedidos para a API

• No Cloud Shell, depois de implementar a API de exemplo, pode enviar-lhe pedidos executando o seguinte script:

  ./query_api.sh
  

O script repete o comando curl que usa para enviar um pedido à API e, em seguida, apresenta o resultado. O resultado é:

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

A API espera um parâmetro de consulta, iataCode, que está definido para um código de aeroporto IATA válido, como SEA ou JFK. Por exemplo:

./query_api.sh JFK

Nota: o App Engine pode demorar alguns minutos a responder com êxito aos pedidos. Se enviar um pedido e receber um erro HTTP 502, 503 ou algum outro erro do servidor, aguarde um minuto e tente novamente o pedido.

Acabou de implementar e testar uma API no Endpoints!

Acompanhamento da atividade da API

Com as APIs implementadas com o Endpoints, pode monitorizar as métricas de operações críticas na Google Cloud consola e obter estatísticas sobre os seus utilizadores e utilização com o Cloud Logging.

1. No Cloud Shell, execute o script de geração de tráfego para preencher os gráficos e os registos:

   ./generate_traffic.sh
   

2. Na Google Cloud consola, consulte os gráficos de atividade da sua API.

   Aceda à página Serviços de pontos finais

   Pode demorar alguns momentos até os pedidos serem refletidos nos gráficos. Enquanto aguarda que os dados sejam apresentados:

   • Se o painel lateral Autorizações não estiver aberto, clique em +Autorizações. O painel Autorizações permite-lhe controlar quem tem acesso à sua API e o nível de acesso.

   • Clique em Histórico de implementação. Este separador apresenta um histórico das suas implementações de API, incluindo a hora de implementação e quem implementou a alteração.

   • Clique em Vista geral. Vê o tráfego a entrar. Depois de o script de geração de tráfego ser executado durante um minuto, verá três linhas no gráfico Latência total (percentis 50, 95 e 98). Estes dados fornecem uma estimativa dos tempos de resposta.

3. Desloque a página para baixo até à tabela abaixo dos gráficos e, em Links, clique em Ver registos para GET/airportName. A página Explorador de registos apresenta os registos de pedidos da API.

4. Abra o Cloud Shell.

   Abra o Cloud Shell

5. Para parar o script, introduza Control+C.

Adicionar uma quota à API

Os pontos finais permitem-lhe definir quotas que lhe permitem controlar a taxa à qual as aplicações podem chamar a sua API. Pode usar quotas para proteger a sua API contra a utilização excessiva por parte de um único cliente.

1. No Cloud Shell, implemente a configuração do Endpoints que tem uma quota.

   ./deploy_api.sh ../openapi_with_ratelimit.yaml
   

   Depois de implementar uma configuração atualizada dos Endpoints, esta fica ativa no prazo de um minuto.

2. Na Google Cloud consola, aceda à página Credenciais.

   Aceda à página Credenciais

3. Clique em Criar credenciais e, de seguida, em Chave da API. É apresentada uma nova chave da API no ecrã.

4. Clique em Copiar file_copy.

5. No Cloud Shell, introduza o seguinte. Substitua YOUR_API_KEY pela chave da API que acabou de criar.

   export API_KEY=YOUR_API_KEY
   

6. Envie um pedido à API através da chave da API que acabou de gerar.

   ./query_api_with_key.sh $API_KEY
   

   O resultado é semelhante ao seguinte:

   curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
   San Francisco International Airport
   

7. A API tem agora um limite de 5 pedidos por minuto. Execute o seguinte comando para enviar tráfego para a API e acionar o limite de quota.

   ./generate_traffic_with_key.sh $API_KEY
   

8. Depois de executar o script durante 5 a 10 segundos, introduza Control+C para o parar.

9. Envie outro pedido autenticado para a API.

   ./query_api_with_key.sh $API_KEY
   

   O resultado é semelhante ao seguinte:

   {
    "code": 8,
    "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
    "details": [
     {
      "@type": "type.googleapis.com/google.rpc.DebugInfo",
      "stackEntries": [],
      "detail": "internal"
     }
    ]
   }
   

Se receber uma resposta diferente, experimente executar o generate_traffic_with_key.sh script novamente e, em seguida, tente novamente.

Parabéns! Limitou a taxa da sua API com êxito. Também pode definir limites variáveis em diferentes métodos de API, criar vários tipos de quotas e monitorizar que consumidores usam que APIs.

Para mais informações, consulte o artigo Acerca das quotas.