Configurar o OpenAPI do Endpoints para o Cloud Run com o ESPv2

Configurar o OpenAPI do Endpoints para o Cloud Run com o ESPv2

OpenAPI   |  gRPC

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 a seguir. É possível conferir as métricas do seu serviço na página Endpoints > Serviços no Google Cloud console.

Observação: no gráfico de exemplo, o ESPv2 e o "back-end" são implantados em duas instâncias separadas do Cloud Run.

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

1. Crie um Google Cloud projeto e, se você não tiver implantado seu próprio Cloud Run, implante um serviço de back-end de amostra. Consulte Antes de começar.
2. Reserve um nome de host do Cloud Run para o serviço ESPv2. Consulte Como reservar um nome de host do Cloud Run.
3. Criar um documento da OpenAPI que descreva sua API e configure as rotas para o Cloud Run. Consulte Como configurar o Endpoints.
4. Implante o documento do OpenAPI para criar um serviço gerenciado. Consulte Como implantar a configuração do Endpoints.
5. 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.
6. 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.
7. Chamar um serviço. Consulte Como enviar uma solicitação à API.
8. Rastreie a atividade para seus serviços. Consulte Como rastrear a atividade da API.
9. Para evitar cobranças na sua conta do Google Cloud . Consulte Limpeza.

Custos

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

• Cloud Run
• Endpoints

Para gerar uma estimativa de custo baseada na sua projeção de uso, utilize a calculadora de preços.

Novos usuários do Google Cloud podem estar qualificados para um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte Limpeza.

Antes de começar

Para configurar:

1. No console Google Cloud , acesse a página Gerenciar recursos e crie um projeto.

   Acessar a página Gerenciar recursos

2. Verifique se o faturamento foi ativado para o projeto.

   Saiba como ativar o faturamento

3. Anote o ID do projeto, porque ele será necessário mais tarde. No restante desta página, esse ID de projeto é chamado de ESPv2_PROJECT_ID.

4. 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 ESPv2_PROJECT_NUMBER.

5. Faça o download e instale a Google Cloud CLI.

   Fazer o download da CLI gcloud

6. 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.

Observação: para aumentar a segurança, configure o serviço de back-end do Cloud Run para permitir o tráfego de entrada apenas de fontes internas. Isso encaminha todas as solicitações externas pelo proxy do ESPv2, impedindo o acesso direto à Internet e centralizando o gerenciamento e a segurança da API. Consulte como controlar a entrada no serviço do Cloud Run para mais detalhes.

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.

Observação: cada serviço ESPv2 do Cloud Run só pode ser associado a um documento da OpenAPI ou a uma configuração de serviço do gRPC. Reserve um novo nome de host do Cloud Run para cada documento.

1. 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 do navegador que é aberta, escolha uma conta que tenha o papel Editor ou Proprietário no projeto Google Cloud que você criou para implantar o ESPv2 no Cloud Run.
2. Defina a região.

   gcloud config set run/region us-central1

3. Implantar a imagem de amostra gcr.io/cloudrun/hello no Cloud Run. Substitua ESPv2_CLOUD_RUN_SERVICE_NAME pelo nome do serviço que você quer usar.

   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, o comando exibirá 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 você definir ESPv2_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 ESPv2_CLOUD_RUN_HOSTNAME.

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

Como configurar o Endpoints

É necessário ter um documento OpenAPI baseado em OpenAPI 2.0 ou OpenAPI 3.x que descreva a superfície dos seus apps e quaisquer requisitos de autenticação. Para saber mais, consulte Versões compatíveis da OpenAPI.

Também é preciso adicionar um campo específico do Google que contenha o URL de cada app para que o ESPv2 tenha as informações necessárias para invocar um app. Se você é novo na OpenAPI, consulte a visão geral da OpenAPI para mais informações.

1. Crie um arquivo de texto chamado openapi-run.yaml. Por conveniência, esta página se refere ao documento da OpenAPI por esse nome de arquivo, mas é possível usar outro nome se você preferir.
2. Seu aplicativo de back-end do App Engine é definido no arquivo openapi-run.yaml, em uma definição de x-google-backend (para OpenAPI 2.0) ou x-google-api-management (para OpenAPI 3.x). Exemplo:

   OpenAPI 2.0

   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

   OpenAPI 3.x

   openapi: 3.0.4
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   servers:
   - url: https://ESPv2_CLOUD_RUN_HOSTNAME
     x-google-endpoint: {}
   x-google-api-management:
     backends:
       cloudrun_backend:
         address: BACKEND_SERVICE_NAME
         protocol: h2
   x-google-backend: cloudrun_backend
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   O recuo é importante para o formato YAML. Por exemplo, o campo host (para OpenAPI 2.0) ou o objeto servers precisa estar no mesmo nível de info.

3. No campo address, 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.

4. Especifique o nome do host do serviço. O valor necessário depende da versão da especificação OpenAPI que você está usando.

   OpenAPI 2.0

   No campo host, especifique ESPv2_CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que foi reservada 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

   OpenAPI 3.x

   No campo url do objeto servers, especifique o URL completo, incluindo o identificador de protocolo https:// e ESPv2_CLOUD_RUN_HOSTNAME, a parte do nome do host do URL que foi reservada em Como reservar um nome de host do Cloud Run. Exemplo:

   openapi: 3.0.4
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   servers:
   - url: https://gateway-12345-uc.a.run.app
     x-google-endpoint: {}

5. Anote o valor da propriedade title no arquivo openapi-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.

6. 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 configurar o Endpoints para exigir uma chave de API

Para controlar o acesso à API, configure o Endpoints para exigir uma chave de API. Os clientes que chamam sua API precisam fornecer uma chave de API associada ao projeto. Consulte Como restringir o acesso à API com chaves de API para mais informações.

Se você ainda não tiver uma chave de API associada ao projeto Google Cloud que está usando neste guia de início rápido, adicione uma seguindo as etapas em Criar uma chave de API.

Para testar a aplicação da chave de API usando uma chave associada ao seu projeto Google Cloud , siga estas etapas:

1. Ative o suporte à chave de API para seu serviço. Digite o seguinte comando:
   • ESPv2_CLOUD_RUN_HOSTNAME é o componente de nome de host do URL designado para o serviço ESPv2 no Cloud Run. Ele é usado no campo host do documento da OpenAPI para especificar o local em que a API está hospedada.

   gcloud services enable ESPv2_CLOUD_RUN_HOSTNAME

2. Abra o arquivo openapi-run.yaml do projeto.
3. Adicione o esquema de segurança api_key na seção securityDefinitions. Isso define um esquema de segurança chamado api_key que procura a chave de API no cabeçalho x-api-key.

   swagger: '2.0'
   host: ESPv2_CLOUD_RUN_HOSTNAME
   info:
     version: 1.0.0
     title: Cloud Endpoints + Cloud Run
   schemes:
     - https
   produces:
     - application/json
   securityDefinitions:
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
       

4. Aplique o esquema de segurança api_key a todos os métodos da API adicionando a diretiva security: - api_key: [] no nível superior do arquivo openapi-run.yaml.

   swagger: '2.0'
   host: ESPv2_CLOUD_RUN_HOSTNAME
   info:
     version: 1.0.0
     title: Cloud Endpoints + Cloud Run
   schemes:
     - https
   produces:
     - application/json
   securityDefinitions:
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
   security:
     - api_key: []
       

5. Se você quiser proteger métodos específicos em vez de toda a API, adicione uma diretiva security: [] vazia no nível superior e, em seguida, adicione a diretiva security: - api_key: [] à definição do método específico que você quer proteger.

     paths:
       /shelves:
         get:
           summary: Lists all shelves
           operationId: listShelves
           security: []
         post:
           summary: Creates a new shelf
           operationId: createShelf
           security:
           - api_key: []
       

6. Depois de modificar o arquivo openapi-run.yaml, implante a configuração atualizada no serviço do Endpoints.

Como chamar uma API usando uma chave de API

Se uma API ou método de API exigir uma chave de API, forneça a chave usando um parâmetro de consulta chamado key, conforme mostrado no seguinte exemplo de curl:

 curl "${ESPv2_CLOUD_RUN_HOSTNAME}/echo?key=${API_KEY}"

Práticas recomendadas

Se você depende de chaves de API para proteger o acesso aos dados do usuário e à API, defina a flag --service_control_network_fail_policy como close ao configurar as opções de inicialização do Extensible Service Proxy V2 (ESPv2). O valor padrão da sinalização é open..

O ESPv2 chama o Service Control para verificar as chaves de API. Se houver falhas de rede ao se conectar ao Service Control e o ESPv2 não puder verificar a chave de API, todas as possíveis solicitações feitas à API com chaves fraudulentas serão rejeitadas.

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:

1. Verifique se você está no diretório que contém o documento do OpenAPI.

2. Faça upload da configuração e crie um serviço gerenciado:

   gcloud endpoints services deploy openapi-run.yaml \
     --project ESPv2_PROJECT_ID

   Isso cria um novo serviço do Endpoints com o nome especificado no campo host do arquivo openapi-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 [ESPv2_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 ver a configuração do serviço e o histórico de implantação na página Endpoints > Serviços do Google Cloud console.

   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 doGoogle Cloud atual em que esses serviços foram explicitamente desativados.

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:

• 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:

1. Faça o download deste script em sua 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.

2. 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

   Observação :

   Esse script foi criado para criar uma pasta no diretório /tmp. Verifique se você tem acesso de gravação ao diretório /tmp ao executar esse script.

   Se o acesso de gravação não estiver disponível para o diretório /tmp, modifique o script para especificar um diretório alternativo em que você tenha o acesso necessário para criar pastas.

   Para ESPv2_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

3. 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 ESPv2_VERSION no nome da imagem de saída. O upload da imagem de saída é feito para:

   gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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

1. Implante o serviço do Cloud Run do ESPv2 com a nova imagem que você criou anteriormente. Substitua ESPv2_CLOUD_RUN_SERVICE_NAME pelo mesmo nome de serviço do Cloud Run que você usou quando reservou originalmente o nome do host em Como reservar um nome de host 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

   Observação : se você quiser que o ESPv2 gerencie o acesso, use a flag --allow-unauthenticated para garantir que o ESPv2 verifique o token JWT. Se a flag não for usada, o token JWT será interceptado e verificado pelo servidor IAM de 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. Recomendamos usar o IAM em vez do ESPv2 para gerenciar o acesso.

2. 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 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 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.

3. Conceda permissão ao ESPv2 para chamar o Service Management e o Service Control.
Observação : essa etapa não é necessária se a instância do Cloud Run do ESPv2 for implantada sem a sinalização --service-account
• No console Google Cloud , acesse a página do Cloud Run.

Acessar 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:

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

Para mais informações, consulte O que são funções e permissões?
4. Conceda permissão ao ESPv2 para invocar seus serviços do Cloud Run. Execute o seguinte comando para cada serviço. No seguinte comando:
   Observação:

   Esta etapa não será necessária se o serviço ESPv2 do Cloud Run for implantado sem usar a sinalização --service-account e o serviço de back-end BACKEND_SERVICE_NAME for implantado no projeto ESPv2_PROJECT_NUMBER.

   • 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 ESPv2_PROJECT_NUMBER pelo número do projeto criado para o ESPv2. Uma maneira de encontrar isso é acessar a página IAM no console Google Cloud e encontrar a conta de serviço de computação padrão, que é a conta de serviço usada na flag "member".

   gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:[e-mail]" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

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.

1. 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 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 receber uma resposta bem-sucedida, consulte Como solucionar problemas em erros de resposta.

Você acaba de implantar e testar uma API no Endpoints.

Observação: se quiser nos contar do que você gostou neste tutorial, envie um feedback na parte inferior desta página. Isso é muito importante para a melhoria dos tutoriais.
Se ocorrer um erro, entre no grupo do Google google-cloud-endpoints e informe o que aconteceu. Nesse grupo, são enviadas respostas de outros usuários do Endpoints e de engenheiros do Google, que o monitoram.

Rastrear a atividade da API

1. Veja os gráficos de atividade para 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.

2. Verifique os registros de solicitações da API na página "Visualizador de registros". Ver registros de solicitações do Endpoints

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga as etapas abaixo.

Consulte Como excluir uma API e as instâncias relacionadas para mais informações sobre como interromper os serviços usados neste tutorial.

A seguir

• Saiba mais sobre o Cloud Run
• Saiba mais sobre como implantar a configuração do Endpoints
• Compartilhe a API com outro desenvolvedor
• Aprenda sobre autenticação
• Conheça as opções de suporte da comunidade