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

Nesta página, mostramos como configurar o Cloud Endpoints para o App Engine. O Endpoints usa o Extensible Service Proxy V2 Beta (ESPv2 Beta) como um gateway de API (link em inglês). Para fornecer o gerenciamento de APIs do App Engine, implante o contêiner pré-construído do ESPv2 Beta para Cloud Run. Assim, você protege seu aplicativo por meio do Identity Aware Proxy (IAP) para que apenas o ESPv2 Beta possa invocá-lo.

Com essa configuração, o ESPv2 Beta 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 ESPv2 Beta 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.

Como migrar para o ESPv2 Beta

Versões anteriores do Cloud Endpoints permitiam o uso do Extensible Service Proxy (ESP) com o Cloud Run. Se você tiver APIs existentes que quer migrar para o ESPv2 Beta, consulte Migrar para o Extensible Service Proxy V2 Beta para saber mais.

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 back-end de amostra. Consulte Antes de começar.
  2. Configure o IAP para proteger seu aplicativo. Consulte Configurar o IAP.
  3. Reserve um nome de host do Cloud Run para o serviço ESPv2 Beta. Consulte Como reservar um nome de host do Cloud Run.
  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. Crie uma nova imagem do Docker do ESPv2 Beta com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2 Beta.
  7. Implante o contêiner do ESPv2 Beta no Cloud Run. Em seguida, conceda ao ESPv2 Beta a permissão de Gerenciamento de identidade e acesso (IAM, na sigla em inglês) para invocar seu serviço. Consulte Como implantar o contêiner do ESPv2 Beta.
  8. Invoque um aplicativo. Consulte Como enviar uma solicitação à API.
  9. Rastreie as atividades nos aplicativos. Consulte Como rastrear a atividade da API.
  10. Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

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 back-end do App Engine, siga as etapas no Guia de início rápido do App Engine. Anote a região e o ID do projeto em que seus aplicativos estã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 do OAuth, que é chamado de IAP_CLIENT_ID neste tutorial.

Como reservar um nome de host do Cloud Run

É preciso reservar um nome do host do Cloud Run para o serviço ESPv2 Beta para configurar o documento da OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do host, você implantará um contêiner de amostra no Cloud Run. Posteriormente, você implantará o contêiner do ESPv2 Beta no mesmo serviço do 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 ESPv2 Beta no Cloud Run.
  2. Defina a região.
    gcloud config set run/region us-central1
  3. Implantar a imagem de amostra gcr.io/cloudrun/hello no Cloud Run. Substitua CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.
    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/cloudrun/hello" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    

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

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    Por exemplo, se você definir CLOUD_RUN_SERVICE_NAME para gateway:

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

    Neste exemplo, https://gateway-12345-uc.a.run.app é o CLOUD_RUN_SERVICE_URL e gateway-12345-uc.a.run.app é o CLOUD_RUN_HOSTNAME.

  4. Anote CLOUD_RUN_SERVICE_NAME e CLOUD_RUN_HOSTNAME. Depois, implante o ESPv2 Beta no serviço CLOUD_RUN_SERVICE_NAME Cloud Run. Especifique CLOUD_RUN_HOSTNAME no campo host do documento da OpenAPI.

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 é preciso adicionar um campo específico do Google que contenha o URL de cada aplicativo para que o ESPv2 Beta tenha as informações necessárias para invocar um aplicativo. Se você é novo no OpenAPI, consulte a visão geral do OpenAPI para ver 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. Seu aplicativo de back-end do App Engine é definido na parte superior do arquivo openapi-appengine.yaml, em uma definição de x-google-backend. 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
        protocol: h2
      paths:
        /:
          get:
            summary: Greet a user
            operationId: hello
            responses:
              '200':
                description: A successful response
                schema:
                  type: string
    
    O recuo é importante para o formato yaml. Por exemplo, o campo host deve estar no mesmo nível de info.
  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, especifique CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que foi reservada acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo, https://. 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
    
  5. Anote o valor da propriedade title no arquivo openapi-appengine.yaml:

    title: Cloud Endpoints + App Engine

    O valor da propriedade title se tornará o nome do serviço do Endpoints depois que você implantar a configuração.

  6. Salve o documento do 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, uma mensagem parecida com esta será exibida:

    Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

    CONFIG_ID é o ID exclusivo de configuração de serviço do Endpoints criado pela implantação. Exemplo:

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

    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 do 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 o ENDPOINTS_SERVICE_NAME, é possível:

  • 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 a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo host da especificação do OpenAPI. Para gRPC, o ENDPOINTS_SERVICE_NAME é o que você especificou no campo name da configuração do gRPC Endpoints.

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

Como criar uma nova imagem do ESPv2 Beta

Crie a configuração do serviço do Endpoints em uma nova imagem docker do ESPv2 Beta Em seguida, você implantará essa imagem no serviço reservado do Cloud Run.

Para criar a configuração do serviço em uma nova imagem docker do ESPv2 Beta:

  1. Faça o download deste script em sua máquina local em que o SDK da gcloud está instalado.

  2. Execute o script com o seguinte comando:

    chmod +x gcloud_build_image
    
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    Para CLOUD_RUN_HOSTNAME, especifique o nome do host do URL que você reservou acima em Como reservar um nome de host do Cloud Run. Não inclua o identificador de protocolo, https://.

    Exemplo:

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01r0 -p your-project-id
  3. O script usa o comando da gcloud para fazer o download da configuração do serviço, criar essa configuração em uma nova imagem do ESPv2 Beta e fazer upload da nova imagem para o registro de contêiner do projeto. O script usa automaticamente a versão mais recente do ESPv2 Beta, indicada pela ESP_VERSION no nome da imagem de saída. O upload da imagem de saída é feito para:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

    Por exemplo:

    gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

Como implantar o contêiner do ESPv2 Beta

  1. Implante o serviço do Cloud Run do ESPv2 Beta com a nova imagem que você criou acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando reservou originalmente o nome do host acima em Como reservar um nome de host do Cloud Run:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  2. Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2 Beta, como ativar o CORS, por exemplo, passe os argumentos na variável de ambiente ESPv2_ARGS:

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --allow-unauthenticated \
      --platform managed \
      --project ESP_PROJECT_ID

    Para mais informações e exemplos sobre como configurar a variável de ambiente ESPv2_ARGS, incluindo a lista de opções disponíveis e informações sobre como especificar várias opções, consulte Sinalizações do Extensible Service Proxy V2 Beta.

  3. Conceda permissão ao ESPv2 Beta para invocar seu app protegido pelo IAP. Execute o seguinte comando para cada serviço. Realize estas etapas no comando a seguir:
    • Substitua APP_PROJECT_ID pelo nome do ID do projeto do App Engine.
    • Substitua ESP_PROJECT_NUMBER pelo número do projeto criado para o ESPv2 Beta. Uma maneira de encontrá-lo é acessar o Console de IAM e procurar 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"
        

Para mais informações, consulte Como gerenciar o acesso usando o IAM.

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}/"

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/").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/
    

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