Configurar o Cloud Endpoints OpenAPI para o ambiente padrão com ESPv2

Nesta página, mostramos como configurar o Cloud Endpoints para o App Engine. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Implante o contêiner ESPv2 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 apenas o ESPv2 possa invocá-lo.

Com essa configuração, o ESPv2 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 coleta e reporta a telemetria, conforme a figura abaixo. É possível visualizar métricas do seu app na página Endpoints > Serviços no console do Google Cloud.

Arquitetura do Endpoints

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

Como migrar para o ESPv2

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, consulte Migrar para o Extensible Service Proxy V2 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.

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.
Configure o IAP para proteger seu aplicativo. Consulte Configurar o IAP.
Reserve um nome de host do Cloud Run para o serviço ESPv2. Consulte Como reservar um nome de host do Cloud Run.
Crie um documento OpenAPI que descreva sua API e configure as rotas para seu App Engine. Consulte Como configurar o Endpoints.
Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
Crie uma nova imagem do Docker do ESPv2 com a configuração do serviço do Endpoints. Consulte Como criar uma nova imagem do ESPv2.
Implante o contêiner do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 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.
Invoque um aplicativo. Consulte Como enviar uma solicitação à API.
Rastreie as atividades nos aplicativos. Consulte Como rastrear a atividade da API.
Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Para configurar:

No console do Google Cloud, acesse a página Gerenciar recursos e crie um projeto.
Acessar a página Gerenciar recursos
Verifique se o faturamento foi ativado para o projeto.
Saiba como ativar o faturamento
Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de ESP_PROJECT_ID.
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.
Faça o download e instale a Google Cloud CLI.
Fazer o download da CLI gcloud
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 para configure 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ê deploy o contêiner do ESPv2 no mesmo serviço do Cloud Run.

Verifique se a CLI gcloud está autorizada a acessar seus dados e serviços.
1. Faça login.
```
gcloud auth login
```
2. Na nova guia aberta do navegador, escolha uma conta que tenha o papel de Editor ou Proprietário no projeto do Google Cloud que você criou para implantar o ESPv2 no Cloud Run.

Defina a região.

gcloud config set run/region us-central1

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.

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

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 é preciso adicionar um campo específico do Google que contenha o URL de cada aplicativo para que o ESPv2 tenha as informações necessárias para invocar um aplicativo. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para ver mais informações.

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.

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: CLOUD_RUN_HOSTNAME
  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.

No campo address na seção x-google-backend, substitua APP_PROJECT_ID pelo ID do projeto do Google Cloud, REGION pela região do GCP em que você implantou o App Engine e IAP_CLIENT_ID pelo ID do cliente OAuth criado ao configurar o IAP.
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
```
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.
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:

Verifique se você está no diretório que contém o documento do OpenAPI.
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 no console do Google 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	Cargo
`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:

Depois de implantar a configuração do Endpoints, acesse a página Endpoints 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

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

Observação :

Esta etapa é obrigatória.

A configuração do serviço precisa ser integrada a uma nova imagem docker porque o Cloud Run é um serviço de escalonamento para zero. Isso significa que, quando não houver tráfego, todas as instâncias serão excluídas. Quando o tráfego aumenta, novas instâncias são criadas sob demanda. Esse tipo de criação de instância de serviço também é chamado de inicialização a frio. Consulte a documentação sobre simultaneidade do Cloud Run para saber mais.

Se a imagem do Docker não tivesse a configuração de serviço integrada, o Cloud Run precisaria fazer duas chamadas de API ao Google ServiceManagement na inicialização a frio. Essas chamadas são descontadas da sua cota da API Google ServiceManagement.

Ao criar a configuração do serviço na imagem docker do ESPv2, você remove as duas chamadas de API e evita impactar a contagem da cota do serviço Google ServiceManagement Essa etapa também acelera a criação da nova instância de serviço e reduz a latência das solicitações aguardando a nova instância.

Execute esta etapa inteira novamente e reimplante o novo contêiner:

Todas as vezes que você modificar e reimplantar a configuração do serviço do Endpoints. Caso contrário, as alterações na configuração do serviço não serão propagadas para o ESPv2.
Quando uma nova versão do ESPv2 for lançada. Caso contrário, a versão mais antiga do ESPv2 permanecerá implantada.

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

Faça o download deste script na máquina local em que a CLI gcloud está instalada.

Observação :
Esse script requer bash. Se você não estiver usando o macOS/Linux poderá executá-lo no Cloud Shell, no Compute Engine ou no subsistema do Windows para Linux.

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

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 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, 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
```
Exemplo:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Observação :
Transmita a sinalização -z para o script gerar a imagem em um local de registro diferente.

Por exemplo, para enviar a imagem gerada do ESPv2 para um data center da União Europeia, transmita -z eu para o script.

Como implantar o contêiner do ESPv2

Implante o serviço do Cloud Run do ESPv2 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
```
Observação :
Se você quiser que o ESPv2 gerencie o acesso, use a sinalização --allow-unauthenticated para garantir que o ESPv2 verifique o token JWT. Se a sinalização não for usada, o token JWT será interceptado e verificado pelo servidor IAM de <a=" docs=""managing-access"="" run="" securing="">controle de acesso do Cloud Run. Como o IAM e o ESPv2 usam o mesmo cabeçalho de autorização, eles não funcionam juntos. Use apenas um deles. Recomenda-se usar o IAM em vez do ESPv2 para gerenciar o acesso.</a=">
Se você quiser configurar o Endpoints para usar opções adicionais de inicialização do ESPv2, como a de ativar o CORS, 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.
Conceda permissão ao ESPv2 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. Uma maneira de encontrar isso é acessar o Console do IAM e encontrar a conta de serviço padrão do Compute Engine, que é a conta de serviço usada na sinalização "membro".
```
  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.

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.

Aplicativo 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 a atividade da API

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

Ver gráficos de atividades do Endpoints

Pode levar alguns instantes até a solicitação aparecer nos gráficos.
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 exemplo. Para saber mais, consulte a Visão geral do Portal do Cloud Endpoints.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, 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.