Configurar a OpenAPI do Cloud Endpoints para o Cloud Run com o ESPv2
Nesta página, mostramos como configurar o Cloud Endpoints para o Cloud Run. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer o gerenciamento de APIs para o Cloud Run, implante o contêiner pré-criado do ESPv2 no Cloud Run. Em seguida, proteja seus serviços usando o IAM do Cloud Run para que o ESPv2 possa invocá-los.
Com essa configuração, o ESPv2 intercepta todas as solicitações para seus serviços e executa as verificações necessárias, como a autenticação, antes de invocar o serviço. Quando o serviço responde, o ESPv2 coleta e relata a telemetria, como mostrado na figura abaixo. É possível conferir as métricas do seu serviço em Endpoints > página 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
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 concluir este tutorial.
- Crie um projeto do Google Cloud e, se você não tiver implantado seu próprio Cloud Run, implante um serviço de back-end amostra. Consulte Antes de começar.
- Reserve um nome de host do Cloud Run para o serviço ESPv2. Consulte Como reservar um nome de host do Cloud Run.
- Criar um documento da OpenAPI que descreva sua API e configure as rotas para o Cloud Run. 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.
- Chamar um serviço. Consulte Como enviar uma solicitação à API.
- Rastreie a atividade para seus serviços. 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.
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 criar um projeto.
Verifique se o faturamento foi ativado para o projeto.
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.
Se você não tiver implantado seu próprio serviço de back-end do Cloud Run, siga as etapas em Guia de início rápido: implantar um contêiner de amostra predefinido para selecionar ou criar um projeto do Google Cloud e implantar um back-end de amostra. Anote a região e o ID do projeto em que seu serviço está implantado. No restante desta página, esse ID do projeto é chamado de BACKEND_PROJECT_ID. O nome do serviço implantado é chamado de BACKEND_SERVICE_NAME.
Como reservar um nome de host do Cloud Run
É preciso reservar um nome do host do Cloud Run para o serviço ESPv2 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 no mesmo serviço do Cloud Run.
-
Verifique se a CLI gcloud tem autorização para acessar seus dados e
serviços.
- Faça login.
gcloud auth login
- 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 no Cloud Run.
- Faça login.
- 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 egateway-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 da OpenAPI baseado na especificação OpenAPI v2.0 (em inglês) que descreve a superfície do seu serviço de back-end e quaisquer requisitos de autenticação. Também é preciso adicionar um campo específico do Google que contenha o URL de cada serviço para que o ESPv2 tenha as informações necessárias para invocar um serviço. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para mais informações.
-
Crie um arquivo de texto chamado
openapi-run.yaml
. Por conveniência, esta página refere-se ao documento da OpenAPI por esse nome de arquivo, mas é possível usar outro nome se você preferir. -
Seu serviço de back-end do Cloud Run é definido na parte superior do arquivo
openapi-run.yaml
, em uma definição dex-google-backend
. Exemplo: O recuo é importante para o formato yaml. Por exemplo,swagger: '2.0' info: title: Cloud Endpoints + Cloud Run description: Sample API on Cloud Endpoints with a Cloud Run backend version: 1.0.0 host: CLOUD_RUN_HOSTNAME schemes: - https produces: - application/json x-google-backend: address: BACKEND_SERVICE_NAME protocol: h2 paths: /hello: get: summary: Greet a user operationId: hello responses: '200': description: A successful response schema: type: string
host
. O campo precisa estar no mesmo nível queinfo
. No campo
address
e na seçãox-google-backend
, substitua BACKEND_SERVICE_NAME pelo URL real do serviço de back-end do Cloud Run, criado na etapa 6 de Antes de começar.Neste exemplo, presumimos que você esteja usando o serviço de back-end
hello
criado em Guia de início rápido: implantar um contêiner de amostra predefinido. Se você estiver usando outro serviço de back-end do Cloud Run, substitua BACKEND_SERVICE_NAME pelo URL do serviço do Cloud Run.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 + Cloud Run description: Sample API on Cloud Endpoints with a Cloud Run backend version: 1.0.0 host: gateway-12345-uc.a.run.app
Anote o valor da propriedade
title
no arquivoopenapi-run.yaml
:title: Cloud Endpoints + Cloud Run
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-run.yaml \ --project ESP_PROJECT_ID
Isso cria um novo serviço do Endpoints com o nome especificado no campo
host
do arquivoopenapi-run.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-run.yaml
novamente no mesmo dia, o número de revisão aumentará no ID de configuração do serviço. É possível consultar a configuração do serviço e as 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 | 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.comgcloud 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 camponame
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.
Para criar a configuração do serviço em uma nova imagem docker do ESPv2:
Fazer o download Roteiro para a máquina local em que a CLI gcloud está instalada.
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://
.Por 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"
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
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 chamar o Service Management e o Service Control.
- No console do Google Cloud, acesse a página do Cloud Run.
- Você pode ver a instância do Cloud Run que implantou e a conta de serviço associada.
- Conceda as permissões necessárias à conta de serviço:
- Conceda permissão ao ESPv2 para invocar seus serviços do Cloud Run. Execute o seguinte comando para cada serviço. Use o comando a seguir:
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está sendo invocado. Se você estiver usando o serviço de back-end criado na Guia de início rápido: implantar um contêiner de amostra predefinido, use
hello
como esse valor. - Substitua ESP_PROJECT_NUMBER pelo número do projeto criado para o ESPv2. Uma forma de descobrir isso é acessar IAM no console do Google Cloud e encontre o Conta de serviço padrão do Compute, que é a conta de serviço usada no a sinalização "member".
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
- Substitua BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está sendo invocado. Se você estiver usando o serviço de back-end criado na Guia de início rápido: implantar um contêiner de amostra predefinido, use
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceController
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}/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 o navegador Chrome extensão Postman solicitação.
- Selecione
GET
como o verbo HTTP. - Para o cabeçalho, selecione a chave
content-type
e o valorapplication/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.
Rastrear a atividade da API
Confira os gráficos de atividade da sua API em 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 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 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.