Esta página foi traduzida pela API Cloud Translation.

Configure o Cloud Endpoints OpenAPI para o Cloud Run com o ESPv2

OpenAPI | gRPC

Esta página mostra como configurar o Cloud Endpoints para o Cloud Run. Os Endpoints usam o Extensible Service Proxy V2 (ESPv2) como um gateway de API. Para fornecer gestão de APIs para o Cloud Run, implemente o contentor ESPv2 pré-criado no Cloud Run. Em seguida, proteja os seus serviços usando o Cloud Run IAM para que o ESPv2 os possa invocar.

Com esta configuração, o ESPv2 interceta todos os pedidos aos seus serviços e realiza todas as verificações necessárias (como a autenticação) antes de invocar o serviço. Quando o serviço responde, o ESPv2 recolhe e comunica a telemetria, conforme mostrado na figura abaixo. Pode ver as métricas do seu serviço na página Endpoints > Serviços 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 o 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 o seu próprio Cloud Run, implemente um serviç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 o 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 um serviço. Consulte o artigo Enviar um pedido para a API.
Monitorize a atividade nos seus serviços. 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

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 o seu próprio serviço de back-end do Cloud Run, siga os passos no Início rápido: implemente um contentor de exemplo pré-criado para selecionar ou criar um Google Cloud projeto e implementar um exemplo de back-end. Tome nota da região e do ID do projeto onde o serviço está implementado. No resto desta página, este ID do projeto é designado por BACKEND_PROJECT_ID. O nome do serviço implementado é denominado BACKEND_SERVICE_NAME.

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 do seu serviço de back-end e quaisquer requisitos de autenticação. Também tem de adicionar um campo específico da 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 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-run.yaml. (Para facilidade, esta página refere-se ao documento OpenAPI por esse nome de ficheiro, mas pode atribuir-lhe outro nome, se preferir.)

O seu serviço de back-end do Cloud Run está definido na parte superior do ficheiro openapi-run.yaml, numa definição x-google-backend. 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: ESPv2_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

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 BACKEND_SERVICE_NAME pelo URL real do serviço do Cloud Run de back-end, criado no passo 6 de Antes de começar.

Este exemplo pressupõe que está a usar o serviço de back-end hellocriado no guia de início rápido: implemente um contentor de exemplo pré-criado. Se estiver a usar um serviço do Cloud Run de back-end diferente, substitua BACKEND_SERVICE_NAME pelo URL do seu serviço do Cloud Run.
No campo host, especifique ESPv2_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 + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
host: gateway-12345-uc.a.run.app
```
Tome nota do valor da propriedade title no ficheiro openapi-run.yaml:
```
title: Cloud Endpoints + Cloud Run
```
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-run.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-run.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 [ESPv2_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-run.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 ESPv2_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 ESPv2_CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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.
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 ESPv2_CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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 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_ID \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController

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

Conceda autorização ao ESPv2 para invocar os seus serviços do Cloud Run. Execute o seguinte comando para cada serviço. No comando seguinte:
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 BACKEND_SERVICE_NAME pelo nome do serviço do Cloud Run que está a ser invocado. Se estiver a usar o serviço de back-end criado no Início rápido: implemente um contentor de exemplo pré-criado, use hello como este valor.
- 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 run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_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.