Implantar uma API gerenciada pelo Cloud Endpoints

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 Endpoints. O código de amostra 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, você pode conferir os gráficos de atividades do Endpoints e os registros de Observabilidade do Google Cloud no console do Google 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:

• Cloud Endpoints para OpenAPI: tutoriais
• Cloud Endpoints para gRPC: tutoriais
• Frameworks do Cloud Endpoints: tutoriais

Antes de começar

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

5. Make sure that billing is enabled for your Google Cloud project.

Como iniciar o Cloud Shell

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

2. Abra o Cloud Shell.

   Abrir o Cloud Shell

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

   

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
   

Observação: se você estiver usando uma máquina Linux ou MacOS e quiser seguir esse guia de início rápido usando seu shell local, faça o download da Google Cloud CLI e siga as instruções usando sua interface de linha de comando local em vez do Cloud Shell.

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
   

2. Acesse o diretório que contém o código de amostra:

   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
   

2. 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 projeto do Google 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

Como ele está criando e configurando o serviço, o Service Management envia informações para o console do 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	Service Management API

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 necessá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.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

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
   

   Observação: com este script, as solicitações são geradas em repetição. O script expira automaticamente em cinco minutos. Para encerrar o script mais cedo, digite Control+C no Cloud Shell.

2. No console do Google Cloud, confira 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.

3. Role a tela até a tabela abaixo dos gráficos e, em Links, clique em Exibir registros paraGET/airportName. A página Visualizador de registros exibirá os registros de solicitações da API.

4. Abra o Cloud Shell.

   Abra o Cloud Shell

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

Como adicionar uma cota à API

Beta

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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
   

   Após a implantação de uma configuração atualizada do Endpoints, ela fica ativa em um minuto.

2. No Console do Google Cloud, acesse a página Credenciais.

   Acessar a página Credenciais

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

4. Clique em Copiar .

5. No Cloud Shell, digite o seguinte comando. Substitua YOUR_API_KEY pela chave de API que você acabou de criar.

   export API_KEY=YOUR_API_KEY
   

6. Envie uma solicitação à API usando a chave de API recém-gerada.

   ./query_api_with_key.sh $API_KEY
   

   A resposta será semelhante a:

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

7. Agora, a API tem um limite de cinco solicitações por minuto. Execute o comando a seguir para enviar o tráfego para a API e acionar o limite da cota.

   ./generate_traffic_with_key.sh $API_KEY
   

8. Depois de executar o script de 5 a 10 segundos, digite Control+C para interromper o script.

9. Envie outra solicitação autenticada à API.

   ./query_api_with_key.sh $API_KEY
   

   O resultado será semelhante a:

   {
    "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 você receber uma resposta diferente, tente executar o script generate_traffic_with_key.sh novamente e, em seguida, tente novamente.

Parabéns! Você criou uma limitação de taxa para sua API. Você também pode definir limites variados em diferentes métodos de API, criar vários tipos de cotas e acompanhar quais consumidores usam quais APIs.

Para mais informações, consulte Sobre cotas.

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

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga estas etapas.

Para evitar cobranças, você pode excluir seu projeto do Google Cloud para interromper o faturamento de todos os recursos usados naquele projeto.

Cuidado: excluir um projeto tem os seguintes efeitos:
• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir 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.

A seguir

• Para uma visão geral do Endpoints:

  • Sobre o Endpoints
  • Endpoints: visão geral da arquitetura

• Para aprender sobre os diferentes frameworks de API compatíveis com o Endpoints:

  • A especificação OpenAPI
  • Endpoints para APIs do gRPC
  • Sobre frameworks do Endpoints

• Para saber como configurar e implantar uma API de amostra, escolha um tutorial de uma das bibliotecas de API:

  • Endpoints para OpenAPI: tutoriais
  • Endpoints para gRPC: tutoriais
  • Endpoints Frameworks: tutoriais