Guia de início rápido do 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 amostra, você pode visualizar os gráficos de atividades do Endpoints e os registros do Stackdriver 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:

Antes de começar

  1. Faça login na sua Conta do Google.

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

  2. No Console do GCP, na página do seletor de projetos, selecione ou crie um projeto do GCP.

    Acesse a página do seletor de projetos

  3. Verifique se o faturamento foi ativado no projeto do Google Cloud Platform. Saiba como confirmar que o faturamento está ativado para seu projeto.

Como iniciar o Cloud Shell

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

  2. Abra o Cloud Shell.

    Abrir o Cloud Shell (em inglês)

    Uma sessão do Cloud Shell é aberta dentro de um novo frame na parte inferior do Console do Cloud. Ela exibe um prompt de linha de comando. 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
    

Buscar o código de exemplo

  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 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]

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

Como rastrear atividade da API

Com as APIs implementadas com o Endpoints, você pode monitorar métricas de operações importantes no Console do Cloud e ter insights sobre seus usuários e a utilização com o Stackdriver Logging.

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

    ./generate_traffic.sh
    
  2. No Console do Cloud, veja os gráficos de atividades 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 exibe os registros de solicitações da API.

  4. Abra o Cloud Shell.

    Abrir o Cloud Shell

  5. Para interromper o script, digite Ctrl+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
    

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

  2. No Console do 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 file_copy.

  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 Ctrl-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 exemplo. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, 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.

  1. No Console do GCP, acesse a página Gerenciar recursos.

    Acessar a página Gerenciar recursos

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

A seguir