Implantar uma API gerenciada pelo Cloud Endpoints

Neste guia de início rápido, orientamos você na implantação de uma API de amostra, gerenciada pelo Cloud Endpoints. O exemplo de código inclui:

  • uma API REST que você pode consultar caso queira encontrar o nome de um aeroporto a partir do código IATA de três letras;
  • um script que faz upload da configuração da API para o Endpoints;
  • um script que implanta um back-end de ambiente flexível do App Engine para hospedar a API de amostra.

Depois de enviar solicitações para a API de exemplo, é possível visualizar os gráficos de atividades do Endpoints e os registros do Google Cloud Observability no consoleGoogle Cloud . Essas ferramentas permitem monitorar suas APIs e receber insights sobre seu uso.

Neste guia de início rápido, são usados scripts para simplificar as etapas de configuração para você ver rapidamente os gráficos de atividade e os registros em ação. Para saber como configurar e implantar uma API de amostra, escolha um tutorial de uma das bibliotecas de API:

Antes de começar

  1. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  3. Verify that billing is enabled for your Google Cloud project.

Funções exigidas

Para receber as permissões necessárias para implantar e gerenciar uma API, peça ao administrador para conceder a você no projeto os papéis do IAM a seguir:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como iniciar o Cloud Shell

  1. No console Google Cloud , verifique se você está no projeto que quer usar para a API de amostra.

  2. Abra o Cloud Shell.

    Abra o Cloud Shell

    Uma sessão do Cloud Shell é aberta em um novo frame na parte de baixo do console doGoogle Cloud , e um prompt de linha de comando é exibido. A inicialização da sessão pode levar alguns segundos.

    Sessão do Cloud Shell

  3. Se você estiver usando um projeto existente, verifique se 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, digite o seguinte comando para receber a API e os scripts de amostra:
git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
  1. Acesse o diretório que contém o exemplo de código:
cd endpoints-quickstart

Como implantar a configuração do Endpoints

Para publicar uma API REST no Endpoints, é necessário um arquivo de configuração OpenAPI que descreva a API. A API de exemplo vem com um arquivo OpenAPI pré-configurado chamado openapi.yaml.

O Endpoints usa o Service Management, um serviço de infraestrutura do Google Cloud para criar e gerenciar APIs e serviços. Para usar o Endpoints para gerenciar uma API, implante o arquivo de configuração OpenAPI da API no Service Management.

Para implantar a configuração do Endpoints:

  1. No Cloud Shell, no diretório endpoints-quickstart, digite o seguinte:
cd scripts
  1. Execute este script, que está incluso na amostra:
./deploy_api.sh

O Endpoints usa o campo host no arquivo de configuração da 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 você prepara um arquivo de configuração OpenAPI para seu próprio serviço, isso deve ser feito manualmente.

Em seguida, o script implanta a configuração da OpenAPI para o Service Management usando o comando: gcloud endpoints services deploy openapi.yaml

Durante a criação e a configuração do serviço, o Service Management envia informações para o console Google Cloud . Ignore os avisos sobre os caminhos em openapi.yaml que não exigem uma chave de API. Na conclusão bem-sucedida, você vê uma linha semelhante à seguinte, que exibe o código de 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]

Ativação de serviços obrigatórios

No mínimo, o Endpoints requer que os seguintes serviços do Google estejam ativados:

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

Na maioria dos casos, a implantação da configuração do Endpoints ativa os serviços necessários.

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

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

Implantar o back-end da API

Até agora, você implantou a configuração de OpenAPI no Service Management, mas ainda não implantou o código para exibir o back-end da API. O script deploy_app.sh incluído no exemplo cria um ambiente flexível do App Engine para hospedar o back-end da API e, em seguida, implanta a API no App Engine.

Para implantar 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 leva alguns minutos. Depois que o aplicativo é criado, a saída é:

Success! The app is now created.

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

A saída é:

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

A implantação da API no App Engine leva alguns minutos. Quando a API é implantada com sucesso no App Engine, a saída é:

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

Como enviar solicitações à API

  • No Cloud Shell, depois de implantar a API de amostra, você pode enviar solicitações para ele executando o seguinte script:
./query_api.sh

O script ecoa o comando curl que ele usa para enviar uma solicitação à API e, em seguida, exibe o resultado. A saída é:

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 como um código do aeroporto IATA válido, como SEA ou JFK. Por exemplo:

./query_api.sh JFK

Observação: o App Engine pode levar alguns minutos para responder às solicitações. Se você enviar uma solicitação e receber um erro HTTP 502, 503 ou outro erro de servidor, aguarde um minuto e tente enviar a solicitação novamente.

Você acaba de implantar e testar uma API no Endpoints.

Rastrear a atividade da API

Com as APIs implantadas com o Endpoints, você pode monitorar métricas de operações importantes no console do Google Cloud e receber insights sobre seus usuários e o uso com o Cloud Logging.

  1. No Cloud Shell, execute o script de geração de tráfego para preencher os gráficos e registros:
./generate_traffic.sh
 
Note: This script generates requests in a loop and automatically times out
in 5 minutes. To end the script sooner, enter `Control+C` in
Cloud Shell.

  1. No Google Cloud console, veja os gráficos de atividade da sua API.

    Ir para a página Serviços do Endpoints

    Pode levar alguns instantes para que as solicitações sejam refletidas nos gráficos. Enquanto você espera os dados serem exibidos:

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

    • Clique em Histórico de implantação. Esta guia exibe um histórico de implantações da API, inclusive o horário da implantação e quem fez a alteração.

    • Clique em Visão geral. Você vê o tráfego entrando. Depois que o script de geração de tráfego estiver em execução por um minuto, você vê três linhas no gráfico de Latência total (percentis 50, 95 e 98). Esses dados fornecem uma estimativa dos tempos de resposta.

  2. Abaixo dos gráficos, em Links, clique em Exibir registros para GET/airportName. A página Visualizador de registros exibirá os registros de solicitações da API.

  3. Abra o Cloud Shell.

    Abra o Cloud Shell

  4. Para interromper o script, digite Control+C.

Como adicionar uma cota à API

O Endpoints permite definir cotas que permitem controlar a taxa na qual os aplicativos podem chamar a API. Você pode usar cotas para proteger sua API de uso excessivo por um único cliente.

  1. No Cloud Shell, implemente a configuração do Endpoints que tem uma cota.
./deploy_api.sh ../openapi_with_ratelimit.yaml
 
After you deploy an updated Endpoints configuration, it
becomes active within a minute.

  1. No Google Cloud console, acesse a página Credenciais.

    Acessar a página Credenciais

  2. Clique em Criar credenciais e, em seguida, clique em Chave de API. Uma nova chave de API é exibida na tela.

  3. Clique em