Primeiros passos com os Endpoints no ambiente padrão do App Engine

Nesta página, mostramos como configurar o Cloud Endpoints para o App Engine. O Endpoints usa o Extensible Service Proxy (ESP) como um gateway de API. Implante o contêiner ESP pré-construído no Cloud Run para fornecer gerenciamento de API para o App Engine. Assim, você protege seu aplicativo por meio do Identity Aware Proxy (IAP) para que o ESP possa invocá-los. Com essa configuração, o ESP intercepta todas as solicitações para o aplicativo e realiza as verificações necessárias (como autenticação) antes de invocar o aplicativo. Quando o aplicativo responde, o ESP reúne e relata a telemetria. É possível visualizar métricas do seu aplicativo na página Endpoints > Serviços no Console do Google Cloud.

Para uma visão geral do Cloud Endpoints, consulte Sobre o Endpoints e Arquitetura do Endpoints.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para que o Endpoints gerencie o aplicativo.

  1. Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio App Engine, implante um aplicativo de amostra. Consulte Antes de começar.
  2. Configure o IAP para proteger seu aplicativo. Consulte Configurar o IAP.
  3. Implante o contêiner ESP no Cloud Run. Consulte Como implantar o ESP.
  4. Crie um documento OpenAPI que descreva sua API e configure as rotas para seu App Engine. Consulte Como configurar o Endpoints.
  5. Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
  6. Configure o ESP para encontrar a configuração do serviço. Consulte Como configurar o ESP.
  7. Invoque um aplicativo. Consulte Como enviar uma solicitação à API.
  8. Rastreie as atividades nos aplicativos. Consulte Como rastrear a atividade da API.
  9. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

Já que o Endpoints para App Engine está na versão Alfa, recomendamos as seguintes ações:

  • Crie um novo projeto do Google Cloud para usar quando implantar o contêiner do ESP no Cloud Run.

  • Crie um projeto novo ou selecione um atual para seu App Engine.

Para configurar:

  1. No Console do Cloud, acesse a página Gerenciar recursos e crie um projeto.

    Acessar a página Gerenciar recursos

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

    Saiba como ativar o faturamento

  3. Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID do projeto é chamado de ESP_PROJECT_ID.

  4. Anote o número do projeto, porque ele será necessário mais tarde. No restante desta página, esse número de projeto é chamado de ESP_PROJECT_NUMBER.

  5. Faça o download do SDK do Cloud e instale-o.

    Fazer o download do Cloud SDK

  6. Se você não tiver implantado seu próprio Google App Engine, siga as etapas no Guia de início rápido do Google App Engine para que sua linguagem use a ferramenta da linha de comando gcloud a fim de selecionar ou criar um projeto do Google Cloud e implantar um aplicativo de amostra. Anote a região e o ID do projeto em que seus aplicativos são implantados. No restante desta página, esse ID do projeto é chamado de APP_PROJECT_ID.

Configurar o IAP para proteger o aplicativo

Para proteger seu aplicativo do App Engine, você precisa usar o Identity Aware Proxy (IAP) para garantir que as solicitações sejam autenticadas.

Siga as etapas para Ativar o IAP e verifique se você consegue fazer login no seu aplicativo.

Além disso, ao configurar o cliente OAuth, anote o client_id OAuth, que será chamado de IAP_CLIENT_ID neste guia de início rápido.

Como implantar o ESP

Para implantar o contêiner ESP no Cloud Run.

  1. Verifique se o SDK do Cloud tem autorização para acessar seus dados e serviços:
    1. Faça login.
      gcloud auth login
    2. Na nova guia do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESP no Cloud Run.
  2. Defina a região. Atualmente, apenas us-central1 é compatível com o Cloud Run.
    gcloud config set run/region us-central1
  3. Implemente o ESP no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.
    gcloud beta run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:1.30.0" \
        --allow-unauthenticated \
        --project=ESP_PROJECT_ID
    

    Após a conclusão, o comando exibirá uma mensagem semelhante à seguinte:

    Service [gateway] revision [gateway-00001] has been deployed and is serving
    traffic at https://gateway-12345-uc.a.run.app

    No exemplo anterior, gateway é o nome do serviço do Cloud Run.

  4. Anote o nome do host na URL. Você especifica o nome do host no campo host do documento da OpenAPI.
  5. Seu serviço do Cloud Run é público na Internet. Se você quiser adicionar recursos de autenticação, recomendamos usar um dos métodos de autenticação aceitos pelo Endpoints.

Como configurar o Endpoints

É necessário ter um documento OpenAPI baseado na Especificação OpenAPI v2.0 que descreva a superfície de seus aplicativos e quaisquer requisitos de autenticação. Também é necessário adicionar um campo específico do Google que contenha o URL de cada aplicativo para que o ESP tenha as informações necessárias para invocar um aplicativo. Se você ainda não conhece o OpenAPI, consulte Visão geral do OpenAPI para mais informações

  1. Crie um arquivo de texto chamado openapi-appengine.yaml. (Por conveniência, esta página refere-se ao documento do OpenAPI por esse nome de arquivo, mas é possível usar outro nome se você preferir.)
  2. Cada um dos aplicativos precisa ser listado na seção paths do arquivo openapi-appengine.yaml. Exemplo:
      swagger: '2.0'
      info:
        title: Cloud Endpoints + App Engine
        description: Sample API on Cloud Endpoints with an App Engine backend
        version: 1.0.0
      host: HOST
      schemes:
        - https
      produces:
        - application/json
      x-google-backend:
        address: https://APP_PROJECT_ID.REGION.r.appspot.com
        jwt_audience: IAP_CLIENT_ID
      paths:
        /hello:
          get:
            summary: Greet a user
            operationId: hello
            responses:
              '200':
                description: A successful response
                schema:
                  type: string
    
  3. No campo address na seção x-google-backend, substitua APP_PROJECT_ID pelo ID do seu projeto do Google Cloud, REGION pela região do GCP onde você implantou o Google App Engine e IAP_CLIENT_ID pelo ID do cliente OAuth que você criou quando configurou o IAP.
  4. No campo host, adicione o nome do host do URL de veiculação criado pelo Cloud Run para o ESP. Não inclua o identificador de protocolo, https://. Por exemplo:
    swagger: '2.0'
      info:
        title: Cloud Endpoints + App Engine
        description: Sample API on Cloud Endpoints with an App Engine backend
        version: 1.0.0
      host: gateway-12345-uc.a.run.app
    

    Endpoints usam o nome que você configura no campo host como o nome do seu serviço.

  5. Salve o documento da OpenAPI.

Para mais informações sobre os campos no documento da OpenAPI exigido pelo Endpoints, consulte Como configurar o Endpoints.

Como implantar a configuração do Endpoints

Para implantar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Ele utiliza o Service Management para criar um serviço gerenciado.

Para implantar a configuração do Endpoints:

  1. Verifique se você está no diretório que contém o documento do OpenAPI.

  2. Faça upload da configuração e crie um serviço gerenciado:

    gcloud endpoints services deploy openapi-appengine.yaml \
      --project ESP_PROJECT_ID
    

    Isso cria um novo serviço do Endpoints com o nome especificado no campo host do arquivo openapi-appengine.yaml. O serviço é configurado de acordo com o documento da OpenAPI.

Durante a criação e a configuração do serviço, o Service Management envia informações ao terminal. Quando a implantação for concluída, será exibida uma mensagem parecida com esta:

Service Configuration [2019-02-01-r0] uploaded for service [gateway-12345-uc.a.run.app]

No exemplo anterior, 2019-02-01-r0 é o ID de configuração do serviço e gateway-12345-uc.a.run.app é o nome do serviço do Endpoints. O ID de configuração do serviço consiste em um carimbo de data e um número de revisão. Se você implantar openapi-appengine.yaml novamente no mesmo dia, o número de revisão aumentará no ID de configuração do serviço. É possível ver a configuração do serviço e o histórico de implantação na página Endpoints > Serviços no Console do Cloud.

Se você receber uma mensagem de erro, consulte Como solucionar problemas de implantação na configuração do Endpoints.

Como verificar os serviços obrigatórios

No mínimo, o Endpoints e o ESP exigem a ativação dos seguintes serviços do Google:
Nome Título
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control
endpoints.googleapis.com Google Cloud Endpoints

Na maioria dos casos, o comando gcloud endpoints services deploy ativa os serviços necessários. No entanto, o comando gcloud é concluído com êxito, mas não ativa os serviços necessários nas seguintes circunstâncias:

  • Você usou um aplicativo de terceiros, como o Terraform, e não incluiu esses serviços.

  • Você implantou a configuração do Endpoints em um projeto do Google Cloud existente, em que esses serviços foram desativados explicitamente.

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
gcloud services enable endpoints.googleapis.com

Ative também seu serviço do Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar ENDPOINTS_SERVICE_NAME, você pode:

  • Após implantar a configuração do Endpoints, acesse a página Pontos de extremidade no Console do Cloud. A lista de ENDPOINTS_SERVICE_NAME possíveis é mostrada na coluna Nome do serviço.

  • Para OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da sua especificação do OpenAPI. Para gRPC, a ENDPOINTS_SERVICE_NAME é o que você especificou no campo name de sua configuração do gRPC Endpoints.

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

Como configurar o ESP

Configure o ESP para encontrar a configuração do serviço do Endpoints. Em seguida, conceda ao ESP a permissão do Cloud IAM para invocar seu aplicativo protegido por IAP.

Para configurar o ESP:

  1. Defina o nome do serviço do Endpoints para que o ESP possa localizar e carregar a configuração do Endpoints. Realize estas etapas no comando a seguir:

    • Substitua YOUR_SERVICE_NAME pelo nome do serviço do Endpoints. Este é o nome que você especificou no campo host do documento da OpenAPI.
    • Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço do Cloud Run.
    gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
       --set-env-vars ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME \
       --project ESP_PROJECT_ID
    
  2. Se você quiser configurar o Endpoints para usar outras opções de inicialização do ESP, como ativar o CORS, transfira os argumentos na variável de ambiente ESP_ARGS:

    gcloud beta run services update CLOUD_RUN_SERVICE_NAME \
       --set-env-vars="^|^ENDPOINTS_SERVICE_NAME=YOUR_SERVICE_NAME|ESP_ARGS=--rollout_strategy=managed,--cors_preset=basic" \
       --project ESP_PROJECT_ID
    

    Inclua ENDPOINTS_SERVICE_NAME e --rollout_strategy.

  3. Conceda permissão ao ESP para invocar seu aplicativo protegido por IAP. Execute o comando a seguir. Faça o seguinte:

    • Substitua APP_PROJECT_ID pelo nome do ID do projeto do App Engine.
    • substitua ESP_PROJECT_NUMBER pelo número do projeto que você criou para o ESP. Uma maneira de encontrar isso é acessar o Console do IAM e encontrar a conta de serviço de computação padrão, que é a conta de serviço usada na sinalização member.
    gcloud projects add-iam-policy-binding APP_PROJECT_ID \
        --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
        --role "roles/iap.httpsResourceAccessor"
    

Como enviar solicitações à API

Veja nesta seção como enviar solicitações para a API.

  1. Crie uma variável de ambiente para o nome do serviço do Endpoints. Este é o nome que você especificou no campo host do documento da OpenAPI. Por exemplo:
    • Linux ou macOS:

      export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

    • Windows PowerShell:

      $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux ou Mac OS

Use curl para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_HOST definida na etapa anterior.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

PowerShell

Use Invoke-WebRequest para enviar uma solicitação HTTP usando a variável de ambiente ENDPOINTS_HOST definida na etapa anterior.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

No exemplo acima, as duas primeiras linhas terminam em um acento grave. Quando você colar o exemplo no PowerShell, verifique se não há espaço após os acentos graves. Para informações sobre as opções usadas na solicitação de exemplo, consulte Invoke-WebRequest (em inglês) na documentação da Microsoft.

App de terceiros

É possível usar um aplicativo de terceiros, como a solicitação da extensão Postman (em inglês) do navegador Google Chrome.

  • Selecione GET como o verbo HTTP.
  • Para o cabeçalho, selecione a chave content-type e o valor application/json.
  • Use o URL real em vez da variável de ambiente, por exemplo:

    https://gateway-12345-uc.a.run.app/hello
    

Se não receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

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

Como rastrear atividade da API

  1. Veja os gráficos de atividade para sua API na página Endpoints > Serviço no Console do Cloud.

    Ver gráficos de atividades do Endpoints

    Pode levar alguns instantes até a solicitação aparecer nos gráficos.

  2. Verifique os registros de solicitações da API na página "Visualizador de registros".

    Ver registros de solicitações do Endpoints

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.

Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, siga estas etapas:

Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.

A seguir