Esta página foi traduzida pela API Cloud Translation.

Configure o Cloud Endpoints OpenAPI para funções do Cloud Run com o ESPv2

Esta página mostra como configurar os Cloud Endpoints nas funções do Cloud Run. Os Endpoints usam o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gestão de APIs para funções do Cloud Run, implemente o contentor ESPv2 pré-criado no Cloud Run. Em seguida, protege as suas funções através do IAM de funções do Cloud Run para que o ESPv2 as possa invocar.

Com esta configuração, o ESPv2 interceta todos os pedidos às suas funções e realiza todas as verificações necessárias (como a autenticação) antes de invocar a função. Quando a função responde, o ESPv2 recolhe e comunica a telemetria, conforme mostrado na figura seguinte. Pode ver as métricas da sua função na página Endpoints > Services na Google Cloud consola.

Arquitetura de endpoints

Para uma vista geral do Cloud Endpoints, consulte os artigos Acerca dos Endpoints e Arquitetura dos Endpoints.

Migrar para o ESPv2

As versões anteriores do Cloud Endpoints suportavam a utilização do Extensible Service Proxy (ESP) com funções do Cloud Run. Se tiver APIs existentes que quer migrar para o ESPv2, consulte o artigo Migre para o proxy de serviço extensível V2 para saber mais.

Lista de tarefas

Use a seguinte lista de tarefas enquanto segue o tutorial. Todas as tarefas são necessárias para concluir este tutorial.

Crie um Google Cloud projeto e, se ainda não tiver implementado as suas próprias funções do Cloud Run, implemente uma função de back-end de exemplo. Consulte a secção Antes de começar.
Reserve um nome do anfitrião do Cloud Run para o serviço ESPv2. Consulte o artigo Reserve um nome do anfitrião do Cloud Run.
Crie um documento OpenAPI que descreva a sua API e configure as rotas para as suas funções do Cloud Run. Consulte o artigo Configurar pontos finais.
Implemente o documento OpenAPI para criar um serviço gerido. Consulte o artigo Implementar a configuração dos Endpoints.
Crie uma nova imagem Docker do ESPv2 com a configuração do serviço dos Endpoints. Consulte o artigo Criar uma nova imagem do ESPv2.
Implemente o contentor do ESPv2 no Cloud Run. Em seguida, conceda ao ESPv2 a autorização da gestão de identidade e de acesso (IAM) para invocar o seu serviço. Consulte o artigo Implementar o contentor do ESPv2.
Invocar uma função. Consulte o artigo Enviar um pedido para a API.
Monitorize a atividade das suas funções. Consulte o artigo Acompanhamento da atividade da API.
Evite incorrer em cobranças na sua conta Google Cloud . Consulte Limpar.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Antes de usar os Endpoints para funções do Cloud Run, recomendamos que:

Crie um novo Google Cloud projeto para usar quando implementar o contentor do ESPv2 no Cloud Run.
Crie um novo projeto ou selecione um projeto existente para as suas funções do Cloud Run.

Para configurar:

Na Google Cloud consola, aceda à página Gerir recursos e crie um projeto.
Aceda à página Gerir recursos
Certifique-se de que a faturação está ativada para o seu projeto.
Saiba como ativar a faturação
Tome nota do ID do projeto, pois é necessário mais tarde. No resto desta página, este ID do projeto é designado como ESPv2_PROJECT_ID.
Tome nota do número do projeto porque é necessário mais tarde. No resto desta página, este número do projeto é denominado ESPv2_PROJECT_NUMBER.
Transfira e instale a Google Cloud CLI.
Transfira a CLI gcloud
Se não implementou as suas próprias funções do Cloud Run de back-end, siga os passos no Início rápido: usar a CLI Google Cloud para selecionar ou criar um Google Cloud projeto e implementar uma função de exemplo. Tome nota da região e do ID do projeto onde as suas funções estão implementadas. No resto desta página, este ID do projeto é designado por FUNCTIONS_PROJECT_ID.

Reservar um nome de anfitrião do Cloud Run

Tem de reservar um nome de anfitrião do Cloud Run para o serviço ESPv2 para configurar o documento OpenAPI ou a configuração do serviço gRPC. Para reservar um nome do anfitrião, implementa um contentor de exemplo no Cloud Run. Posteriormente, implementa o contentor do ESPv2 no mesmo serviço do Cloud Run.

Certifique-se de que a CLI gcloud está autorizada a aceder aos seus dados e serviços.
1. Inicie sessão.
```
gcloud auth login
```
2. No novo separador do navegador apresentado, escolha uma conta que tenha a função de Editor ou Proprietário no Google Cloud projeto que criou para implementar o ESPv2 no Cloud Run.

Defina a região.

gcloud config set run/region us-central1

Implemente a imagem de exemplo gcr.io/cloudrun/hello no Cloud Run. Substitua ESPv2_CLOUD_RUN_SERVICE_NAME pelo nome que quer usar para o serviço.

gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESPv2_PROJECT_ID

Após a conclusão com êxito, o comando apresenta uma mensagem semelhante à seguinte:

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

Por exemplo, se definir ESPv2_CLOUD_RUN_SERVICE_NAME como 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 v2_CLOUD_RUN_HOSTNAME.

Tome nota de ESPv2_CLOUD_RUN_SERVICE_NAME e ESPv2_CLOUD_RUN_HOSTNAME. Posteriormente, implementa o ESPv2 no serviço do ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. Especifica ESPv2_CLOUD_RUN_HOSTNAME no campo host do seu documento OpenAPI.

Configurar pontos finais

Tem de ter um documento OpenAPI baseado na especificação OpenAPI v2.0 que descreva a superfície das suas funções e quaisquer requisitos de autenticação. Também tem de adicionar um campo específico da Google que contenha o URL de cada função para que o ESPv2 tenha as informações necessárias para invocar uma função. Se for a primeira vez que usa o OpenAPI, consulte a vista geral do OpenAPI para mais informações

Crie um ficheiro de texto denominado openapi-functions.yaml. (Para facilidade, esta página refere-se ao documento OpenAPI por esse nome de ficheiro, mas pode atribuir-lhe outro nome, se preferir.)

Cada uma das suas funções tem de estar listada na secção paths do ficheiro openapi-functions.yaml. Por 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: 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

A indentação é importante para o formato YAML. Por exemplo, o campo host tem de estar ao mesmo nível que info.

No campo address na secção x-google-backend, substitua REGION pela Google Cloud região onde a sua função está localizada, FUNCTIONS_PROJECT_ID pelo seu Google Cloud ID do projeto e FUNCTIONS_NAME pelo nome da sua função. Por exemplo:
```
x-google-backend:
  address: https://us-central1-myproject.cloudfunctions.net/helloGET
```
Se quiser proteger a sua função do Cloud Run permitindo apenas que o ESPv2 a invoque, certifique-se de que o campo address inclui o nome da função se o campo jwt_audience não for especificado. Por exemplo:
```
x-google-backend:
  address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
  path_translation: CONSTANT_ADDRESS
```
Se o jwt_audience for especificado, o respetivo valor também deve incluir o nome da função. Por exemplo:
```
x-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
```
O ESPv2 gera um token de ID quando chama a função do Cloud Run para autenticação. O token de ID deve ter um audience adequado que especifique o anfitrião da função e o nome da função. O ESPv2 define o audience para o token de ID com o valor no campo jwt_audience, se for especificado. Caso contrário, usa o campo address.
No campo host, especifique CLOUD_RUN_HOSTNAME, a parte do nome de anfitrião do URL que foi reservada acima em Reservar um nome de anfitrião do Cloud Run. Não inclua o identificador de protocolo, https://. Por 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
```
Tome nota do valor da propriedade title no ficheiro openapi-functions.yaml:
```
title: Cloud Endpoints + GCF
```
O valor da propriedade title torna-se o nome do serviço Endpoints depois de implementar a configuração.
Guarde o documento OpenAPI.

Para ver informações sobre os campos no documento OpenAPI que o Endpoints requer, consulte o artigo Configurar o Endpoints.

Implementar a configuração dos pontos finais

Para implementar a configuração do Endpoints, use o comando gcloud endpoints services deploy. Este comando usa a gestão de serviços para criar um serviço gerido.

Para implementar a configuração dos Endpoints:

Certifique-se de que está no diretório que contém o seu documento OpenAPI.
Carregue a configuração e crie um serviço gerido.
```
gcloud endpoints services deploy openapi-functions.yaml \
    --project ESPv2_PROJECT_ID
```
Esta ação cria um novo serviço de Endpoints com o nome que especificou no campo host do ficheiro openapi-functions.yaml. O serviço está configurado de acordo com o seu documento OpenAPI.

À medida que cria e configura o serviço, o Service Management envia informações para o terminal. Quando a implementação estiver concluída, é apresentada uma mensagem semelhante à seguinte:
```
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
```
CONFIG_ID é o ID exclusivo da configuração do serviço Endpoints criado pela implementação. Por exemplo:
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
O ID de configuração do serviço consiste numa indicação de data/hora seguida de um número de revisão. Se implementar openapi-functions.yaml novamente no mesmo dia, o número de revisão é incrementado no ID de configuração do serviço. Pode ver a configuração do serviço e o histórico de implementação na página Endpoints > Services na Google Cloud consola.

Se receber uma mensagem de erro, consulte o artigo Resolução de problemas da implementação da configuração dos pontos finais.

A verificar os serviços necessários

No mínimo, os pontos finais e o ESP requerem a ativação dos seguintes serviços Google:

Nome	Título
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

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

Se usou uma aplicação de terceiros, como o Terraform, e não incluiu estes serviços.
Implementou a configuração do Endpoints numGoogle Cloud projeto existente no qual estes serviços foram explicitamente desativados.

Use o seguinte comando para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir os serviços necessários listados, ative-os:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Ative também o serviço Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar o ENDPOINTS_SERVICE_NAME, pode:

Após implementar a configuração do Endpoints, aceda à página Endpoints na Cloud Console. A lista de ENDPOINTS_SERVICE_NAME possíveis é apresentada na coluna Nome do serviço.
Para a OpenAPI, o ENDPOINTS_SERVICE_NAME é o que especificou no campo host da sua especificação OpenAPI. Para o gRPC, o ENDPOINTS_SERVICE_NAME é o que especificou no campo name da sua configuração de pontos finais gRPC.

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

Criar uma nova imagem do ESPv2

Crie a configuração do serviço Endpoints numa nova imagem do Docker do ESPv2. Posteriormente, vai implementar esta imagem no serviço do Cloud Run reservado.

Nota:

Este passo é obrigatório.

A configuração do serviço tem de ser incorporada numa nova imagem do Docker porque o Cloud Run é um serviço de dimensionamento para zero. Isto significa que, quando não existe tráfego, todas as instâncias são eliminadas. Quando o tráfego aumenta, são criadas novas instâncias a pedido. Este tipo de criação de instâncias de serviço também é denominado início a frio. Consulte a documentação sobre a concorrência do Cloud Run para mais informações.

Se a imagem do Docker não tivesse a configuração do serviço incorporada, o Cloud Run teria de fazer duas chamadas API para o Google ServiceManagement no arranque a frio. Estas chamadas são contabilizadas na sua quota da API Google ServiceManagement.

Ao incorporar a configuração do serviço na imagem Docker do ESPv2, remove as duas chamadas API e evita afetar a contagem de quotas do serviço Google ServiceManagement. Este passo também acelera a criação da nova instância do serviço e reduz a latência dos pedidos que aguardam a nova instância.

Tem de executar novamente todo este passo e reimplementar o novo contentor:

Sempre que modifica e reimplementa a configuração do serviço Endpoints. Caso contrário, as alterações à configuração do serviço não são propagadas para o ESPv2.
Quando é lançada uma nova versão do ESPv2. Caso contrário, a versão mais antiga do ESPv2 permanece implementada.

Para criar a configuração do serviço numa nova imagem Docker do ESPv2:

Transfira este script para a sua máquina local onde a CLI gcloud está instalada.

Nota:
Este script requer o bash. Se não estiver a usar o macOS/Linux, pode executá-lo no Cloud Shell, Compute Engine ou subsistema Windows para Linux.
Execute o script com o seguinte comando:
```
chmod +x gcloud_build_image

./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESPv2_PROJECT_ID
```
Nota:
Este script foi concebido para criar uma pasta no diretório /tmp. Certifique-se de que tem acesso de escrita ao diretório /tmp quando executar este script.

Se o acesso de escrita não estiver disponível para o diretório /tmp, tem de modificar o script para especificar um diretório alternativo onde tenha o acesso necessário para criar pastas.

Para ESPv2_CLOUD_RUN_HOSTNAME, especifique o nome do anfitrião do URL que reservou acima em Reservar um nome do anfitrião 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 gcloud para transferir a configuração do serviço, criar a configuração do serviço numa nova imagem do ESPv2 e carregar a nova imagem para o registo de contentores do seu projeto. O script usa automaticamente a versão mais recente do ESPv2, indicada por ESPv2_VERSION no nome da imagem de saída. A imagem de saída é carregada para:
```
gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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"
```
Nota:
Transmita a flag -z ao script para gerar a imagem numa localização do registo diferente.

Por exemplo, para enviar a imagem ESPv2 gerada para um centro de dados da União Europeia, transmita -z eu ao script.

Implementar o contentor do ESPv2

Implemente o serviço do Cloud Run do ESPv2 com a nova imagem criada acima. Substitua CLOUD_RUN_SERVICE_NAME pelo mesmo nome do serviço do Cloud Run que usou quando reservou originalmente o nome do anfitrião acima em Reservar um nome do anfitrião do Cloud Run:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID
```
Nota:
Se quiser que o ESPv2 faça a gestão do acesso, use a flag --allow-unauthenticated para garantir que o ESPv2 valida o token JWT. Se a flag não for usada, o token JWT é intercetado e validado pelo servidor IAM de controlo de acesso do Cloud Run. Uma vez que o IAM e o ESPv2 usam o mesmo cabeçalho de autorização, não funcionam em conjunto. Certifique-se de que usa apenas um deles. Recomendamos que use o IAM em vez do ESPv2 para gerir o acesso.</a=">
Se quiser configurar os Endpoints para usar opções de inicialização do ESPv2 adicionais, como ativar o CORS, pode transmitir os argumentos na variável de ambiente ESPv2_ARGS:
```
gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESPv2_PROJECT_ID
```
Para mais informações e exemplos sobre a definição da 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 o artigo Flags beta do proxy de serviço extensível V2.
Conceda autorização ao ESPv2 para chamar o Service Management e o Service Control.

Na Google Cloud consola, aceda à página do Cloud Run.

Aceda à página do Cloud Run

Pode ver a instância do Cloud Run implementada e a conta de serviço associada.
Conceda as autorizações necessárias à conta de serviço:

gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/servicemanagement.serviceController

O que são funções e autorizações?

Conceda autorização ao ESPv2 para invocar as suas funções. Execute o seguinte comando para cada função. No seguinte comando:

Nota:
Este passo não é necessário se o serviço do Cloud Run do ESPv2 for implementado sem usar a flag --service-account e o serviço de back-end BACKEND_SERVICE_NAME for implementado no projeto ESPv2_PROJECT_NUMBER.
- Substitua FUNCTION_NAME pelo nome da sua função e FUNCTION_REGION pela região na qual a função está implementada. Se estiver a usar a função criada no Início rápido: usar a CLI Google Cloud, use helloGET como nome.
- Substitua ESPv2_PROJECT_NUMBER pelo número do projeto que criou para o ESPv2. Uma forma de encontrar esta informação é aceder à página IAM na consola e encontrar a conta de serviço de computação predefinida, que é a conta de serviço usada na flag member. Google Cloud
```
gcloud functions add-iam-policy-binding FUNCTION_NAME \
   --region FUNCTION_REGION \
   --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role "roles/cloudfunctions.invoker" \
   --project FUNCTIONS_PROJECT_ID
```

Para mais informações, consulte o artigo Gerir o acesso através da IAM.

Enviar pedidos para a API

Esta secção mostra como enviar pedidos para a sua API.

Crie uma variável de ambiente para o nome do serviço Endpoints. Este é o nome que especificou no campo host do seu documento 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 um pedido HTTP através da variável de ambiente ENDPOINTS_HOST que definiu no passo anterior.

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

PowerShell

Use Invoke-WebRequest para enviar um pedido HTTP através da variável de ambiente ENDPOINTS_HOST que definiu no passo anterior.

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

No exemplo anterior, as duas primeiras linhas terminam com um acento grave. Quando colar o exemplo no PowerShell, certifique-se de que não existe um espaço após os acentos graves. Para obter informações sobre as opções usadas no pedido de exemplo, consulte Invoke-WebRequest na documentação da Microsoft.

App de terceiros

Pode usar uma aplicação de terceiros, como a extensão do navegador Chrome Postman, para enviar um pedido.

Selecione GET como 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 recebeu uma resposta bem-sucedida, consulte o artigo Resolução de problemas de erros de resposta.

Acabou de implementar e testar uma API no Endpoints!

Acompanhamento da atividade da API

Veja os gráficos de atividade da sua API na página Endpoints > Service na Google Cloud consola.

Veja gráficos de atividade de pontos finais

Pode demorar alguns momentos até que o pedido se reflita nos gráficos.
Consulte os registos de pedidos da sua API na página do explorador de registos. Veja os registos de pedidos de pontos finais

Limpar

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

Consulte o artigo Eliminar uma API e instâncias de API para obter informações sobre como parar os serviços usados por este tutorial.