Guia de início rápido do Cloud Endpoints

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

  • uma REST API 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 Cloud Endpoints;
  • um script que implanta um back-end flexível do App Engine para hospedar a API de amostra.

Depois de enviar algumas solicitações para a API de amostra, você pode ver os gráficos de atividade do Cloud Endpoints e os registros do Stackdriver no console do Google Cloud Platform (GCP). Essas ferramentas permitem monitorar suas APIs e ter insights sobre o uso delas.

Neste 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. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do GCP.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado para o projeto.

    Saiba como ativar o faturamento

Como iniciar o Cloud Shell

  1. Verifique se você está no projeto que quer usar para a API de amostra.

  2. Clique no botão Ativar o Google Cloud Shell no topo da janela do console.

Ativar o Cloud Shell

Uma sessão do Cloud Shell será aberta dentro de um novo frame na parte inferior do console e exibirá um prompt de linha de comando. A inicialização da sessão do shell pode levar alguns segundos.

Sessão do Cloud Shell

Se estiver usando um projeto atual, verifique se você tem a versão mais recente de todos os componentes do gcloud instalada. Basta executar:

gcloud components update

Como receber o código de amostra

  1. Para receber scripts e a API de exemplo, digite o seguinte comando no Cloud Shell:

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. Altere para 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 da OpenAPI que descreva a API. A API de amostra vem com um arquivo OpenAPI pré-configurado chamado openapi.yaml.

O Cloud Endpoints usa o Google Service Management, um serviço de infraestrutura do Cloud Platform, para criar e gerenciar APIs e serviços. Para usar o Endpoints no gerenciamento de uma API, você implanta a configuração OpenAPI da API no Service Management.

Para implantar a configuração do Endpoints:

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

    cd scripts
    
  2. Execute este script, que está incluído na amostra:

    ./deploy_api.sh
    

O Cloud Endpoints usa o campo host no arquivo de configuração OpenAPI para identificar o serviço. O script deploy_api.sh define o código do projeto Cloud como parte do nome configurado no campo host. Quando você preparar um arquivo de configuração OpenAPI para seu próprio serviço, precisará fazer isso manualmente.

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

Durante a criação e a configuração do serviço, o Service Management envia uma grande quantidade de informações para o console. Ignore com segurança os avisos sobre os caminhos no openapi.yaml que não requerem uma chave de API. Após a conclusão bem-sucedida, uma linha semelhante a esta abaixo será exibida, com o código da configuração e o nome do serviço:

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

Como implantar o back-end da API

Até agora, você implantou a configuração da OpenAPI no Service Management, mas não o código que disponibilizará o back-end da API. O script deploy_app.sh incluído na amostra cria um ambiente flexível do App Engine para hospedar o back-end da API e depois implanta a API no App Engine.

Para implantar o back-end da API:

No diretório endpoints-quickstart/scripts, execute este 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"

Demora alguns segundos para que o back-end flexível do App Engine seja criado. Após a criação do App Engine, será exibido o seguinte no console:

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.

Será exibida uma linha semelhante a esta no console:

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

Demora vários minutos para a API ser implantada no App Engine. Após a implantação, será exibida uma linha semelhante a esta:

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

Como enviar solicitações para a API

Após a implantação da API de amostra, você pode enviar solicitações para ela executando este script:

./query_api.sh

O script devolve (ecoa) o comando curl que usa para enviar uma solicitação à API e, em seguida, exibe o resultado, que será algo semelhante a:

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 de 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 Cloud Endpoints.

Como rastrear atividade da API

Com APIs implantadas com o Cloud Endpoints, você pode monitorar métricas de operações críticas no Console do Google Cloud Platform e receber insight sobre seus usuários e uso com o Stackdriver Logging.

  1. Execute o script de geração de tráfego para preencher os gráficos e os registros.

    ./generate_traffic.sh
    
  2. Verifique os gráficos de atividades da API na página "Endpoints".
    Ver gráficos de atividades do Endpoints

    Pode levar alguns instantes para que a solicitação apareça nos gráficos. Enquanto você espera os dados serem exibidos:

    • Se o painel "Permissões" na lateral não estiver aberto, clique em +Permissões. Esse painel permite controlar quem tem acesso à 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ê deverá ver o tráfego entrando. Depois de um minuto executando o script de geração de tráfego, deverão aparecer três linhas no gráfico "Latência total" (50º, 95º e 98º percentis). Esses dados fornecem uma estimativa rápida dos tempos de resposta.

  3. Role até a parte inferior dos gráficos do Endpoints e, em "Método", clique em GET/airportName. A página "Visualizador de registros" exibirá os registros de solicitações para a API.

  4. Clique no botão Ativar o Cloud Shell na parte superior da janela do console para exibir o Cloud Shell.

  5. Insira Ctrl-C para parar o script.

Como adicionar uma cota à API

O Cloud Endpoints permite que você defina cotas para controlar a taxa em que os aplicativos podem chamar sua API. Você pode usar cotas para proteger sua API do uso excessivo por um único cliente.

  1. Implante a configuração do Endpoints que tem 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. Navegue até a página "Credenciais".
    "Credenciais"

  3. Clique em Criar credenciais e selecione Chave de API. Uma nova chave de API é exibida na tela. Clique no ícone de retângulo duplo para copiá-la para a área de transferência.

  4. No Cloud Shell, digite o comando a seguir. Substitua YOUR-API-KEY pela chave de API que você acabou de criar.

    export API_KEY=YOUR-API-KEY
    
  5. Envie uma solicitação à API usando a chave de API recém-gerada.

    ./query_api_with_key.sh $API_KEY
    

    Você verá algo parecido com o seguinte no console:

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

  6. 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
    
  7. Depois de executar o script durante 5 a 10 segundos, digite Ctrl-C para parar o script.

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

    ./query_api_with_key.sh $API_KEY
    

Você verá algo parecido com o seguinte no console:

{
 "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ê limitou a taxa de sua API com sucesso. Também é possível definir limites variáveis em diferentes métodos de API, criar várias espécies de cotas e acompanhar quais consumidores usam quais APIs.

Veja gráficos de atividades do Endpoints

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 que você pode usar 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 sua conta do GCP pelo uso de recursos neste guia de início rápido:

Exclua o projeto do GCP para não ser cobrado pelos recursos usados nele.

  1. No Console do GCP, acesse a página "Projetos".

    Acessar a página Projetos

  2. Na lista de projetos, selecione um e clique em Excluir projeto.
  3. Na caixa de diálogo, digite o código do projeto e clique em Encerrar para excluí-lo.

Próximas etapas

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.