Configurar o OpenAPI do Cloud Endpoints para funções do Cloud Run com o ESPv2
Esta página mostra como configurar o Cloud Endpoints para as funções do Cloud Run. O Endpoints usa o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer o gerenciamento de API para funções do Cloud Run, implante o contêiner pré-criado do ESPv2 no Cloud Run. Em seguida, proteja suas funções usando o IAM das funções do Cloud Run para que o ESPv2 possa invocá-las.
Com essa configuração, o ESPv2 intercepta todas as solicitações para suas funções e realiza todas as verificações necessárias (como autenticação) antes de invocar a função. Quando a função responde, o ESPv2 coleta e relata a telemetria, como mostrado na figura abaixo. É possível conferir as métricas da função 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
Versões anteriores do Cloud Endpoints permitiam o uso do Extensible Service Proxy (ESP) com o Cloud Functions. 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 suas próprias funções do Cloud Run, implante uma função de back-end de 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.
- Crie um documento do OpenAPI que descreva sua API e configure as rotas para suas funções do 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.
- Invoque uma função. Consulte Como enviar uma solicitação à API.
- Rastreie a atividade para suas funções. 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
Antes de usar o Endpoints para funções do Cloud Run, recomendamos que você:
Criar um novo projeto do Google Cloud para usar quando implantar o recipiente do ESPv2 no Cloud Run.
Crie um projeto novo ou selecione um existente para as funções do Cloud Run.
Para configurar:
No console do Google Cloud, acesse a página Gerenciar recursos e crie 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 suas próprias funções de back-end do Cloud Run, siga as etapas em Guia de início rápido: como usar a Google Cloud CLI para selecionar ou criar um projeto do Google Cloud e implantar uma função de exemplo. Anote a região e o ID do projeto em que suas funções são implantadas. No restante desta página, esse ID do projeto é chamado de FUNCTIONS_PROJECT_ID.
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 está autorizada a 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 OpenAPI baseado na Especificação OpenAPI v2.0 que descreva a superfície de suas funções e quaisquer requisitos de autenticação. Você também precisa adicionar um campo específico do Google que contenha a URL de cada função para que o ESPv2 tenha as informações necessárias para invocar uma função. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para mais informações.
-
Crie um arquivo de texto chamado
openapi-functions.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. -
Cada uma de suas funções deve ser listada na seção
paths
do arquivoopenapi-functions.yaml
. Exemplo: O recuo é importante para o formato yaml. Por exemplo, o camposwagger: '2.0' info: title: Cloud Endpoints + GCF description: Sample API on Cloud Endpoints with a Google Cloud Functions backend version: 1.0.0 host: HOST schemes: - https produces: - application/json paths: /hello: get: summary: Greet a user operationId: hello x-google-backend: address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME protocol: h2 responses: '200': description: A successful response schema: type: string
host
precisa estar no mesmo nível deinfo
. -
Na campo
address
na seçãox-google-backend
, substitua REGION pela região do Google Cloud em que a função está localizada, FUNCTIONS_PROJECT_ID pelo ID do projeto do Google Cloud e FUNCTIONS_NAME pelo nome da função. Exemplo: Se quiser proteger a função do Cloud Run permitindo apenas que o ESPv2 a invoque, verifique se o campox-google-backend: address: https://us-central1-myproject.cloudfunctions.net/helloGET
address
inclui o nome da função, casojwt_audience
não seja especificado. Exemplo: Se ox-google-backend: address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME path_translation: CONSTANT_ADDRESS
jwt_audience
for especificado, o valor dele também deverá incluir o nome da função. Exemplo: O ESPv2 gera um token de ID ao chamar a função do Cloud Run para autenticação. O token de ID precisa ter umx-google-backend: address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME path_translation: APPEND_PATH_TO_ADDRESS
audience
adequado que especifique o host e o nome da função. O ESPv2 defineaudience
para o token de ID usando o valor no campojwt_audience
, se especificado. Caso contrário, ele usa o campoaddress
. 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 + GCF description: Sample API on Cloud Endpoints with a Google Cloud Functions backend version: 1.0.0 host: gateway-12345-uc.a.run.app
Anote o valor da propriedade
title
no arquivoopenapi-functions.yaml
:title: Cloud Endpoints + GCF
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-functions.yaml \ --project ESP_PROJECT_ID
Isso cria um novo serviço do Endpoints com o nome especificado no campo
host
do arquivoopenapi-functions.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-functions.yaml
novamente no mesmo dia, o número de revisão aumentará no ID de configuração do serviço. É possível conferir a configuração do serviço e o histórico de implantação na página Endpoints > Serviços do 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 |
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
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 de 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:
Faça o download deste script em sua 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 Beta.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 suas funções. Execute o seguinte comando para cada função. No comando a seguir:
- Substitua FUNCTION_NAME pelo nome da função
e FUNCTION_REGION pela região em que a função
está implantada. Se você estiver usando a função criada no
Guia de início rápido: como usar a Google Cloud CLI,
use
helloGET
como nome. - Substitua ESP_PROJECT_NUMBER pelo
número do projeto criado para o
ESPv2. Uma maneira de encontrar isso é acessar a página IAM no console do Google Cloud e encontrar a conta de serviço de computação padrão, que é a conta de serviço usada na sinalização
member
.
gcloud functions add-iam-policy-binding FUNCTION_NAME \ --region FUNCTION_REGION \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/cloudfunctions.invoker" \ --project FUNCTIONS_PROJECT_ID
- Substitua FUNCTION_NAME pelo nome da função
e FUNCTION_REGION pela região em que a função
está implantada. Se você estiver usando a função criada no
Guia de início rápido: como usar a Google Cloud CLI,
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 por meio do 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 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 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 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 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.