Como usar o gateway de API e o Cloud Run

Nesta página, mostramos como configurar o gateway de API para gerenciar e proteger um serviço de back-end do Cloud Run.

Lista de tarefas

Ao seguir o tutorial, use a lista de tarefas abaixo. Todas as tarefas são necessárias para implantar um gateway de API no serviço de back-end do Cloud Run.

Criar ou selecionar um projeto do Google Cloud.
Se você não implantou seu próprio Cloud Run, implante um serviço de amostra. Consulte a etapa 8 em Antes de começar.
Ative os serviços de gateway de API obrigatórios.
Crie uma especificação OpenAPI que descreva sua API e configure as rotas para seu serviço de back-end do Cloud Run. Consulte Como criar uma configuração de API.
Implante um gateway de API com a configuração de API. Consulte Como implantar um gateway de API.
Rastrear a atividade para seus serviços. Consulte Como rastrear a atividade da API.
Evite cobranças na sua conta do Google Cloud. Consulte Limpeza.

Antes de começar

No console do Google Cloud, acesse a página Painel e selecione ou crie um projeto do Google Cloud.
Ir para a página "Painel"

Observação: se você não pretende manter os recursos criados neste tutorial, crie um novo projeto em vez de selecionar um existente. Depois de concluir esses passos, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.
Verifique se o faturamento foi ativado para o projeto.
Saiba como ativar o faturamento
Anote o ID do projeto que você quer usar neste tutorial. No restante desta página, esse ID de projeto é chamado de PROJECT_ID.
Faça o download e instale a Google Cloud CLI.
Fazer o download da CLI gcloud
Atualize os componentesgcloud:
```
gcloud components update
```
Defina o projeto padrão. Substitua PROJECT_ID pelo ID do projeto do Google Cloud.
```
gcloud config set project PROJECT_ID
```
Se você não tiver implantado seu próprio serviço 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 exemplo. Anote o URL do aplicativo, a região e o ID do projeto em que seus aplicativos são implantados.

Como ativar serviços obrigatórios

A API Gateway requer a ativação dos seguintes serviços do Google:

Nome	Cargo
`apigateway.googleapis.com`	API Gateway
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	API Service Control

Para confirmar que os serviços obrigatórios estão ativados:

gcloud services list

Se você não encontrar os serviços necessários listados, ative-os:

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

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

Como criar uma configuração de API

Antes de usar o gateway de API para gerenciar o tráfego para o back-end do Cloud Run implantado, ele precisa de uma configuração de API.

Você pode criar uma configuração de API usando uma especificação OpenAPI que contenha anotações especializadas para definir o comportamento desejado do gateway de API. Você precisará adicionar um campo específico do Google que contenha o URL de cada aplicativo do Cloud Run para que a API Gateway tenha as informações necessárias para invocar um aplicativo.

Crie um arquivo de texto chamado openapi2-run.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.

Liste cada um dos apps na seção paths do arquivo openapi2-run.yaml, conforme mostrado abaixo.

# openapi2-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

No campo title, substitua API_ID pelo nome da API e optional-string por uma breve descrição de sua escolha. Se a API ainda não existir, o comando para criar a configuração da API também criará a API com o nome especificado. O valor do campo title é usado ao produzir chaves de API que concedem acesso a essa API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura.
No campo address na seção x-google-backend, substitua APP_URL pelo URL real do serviço do Cloud Run (o caminho completo da API chamada). Exemplo: https://hello-abc1def2gh-uc.a.run.app.
Observação: se você planeja usar tags de revisão para controlar a versão do back-end do serviço do Cloud Run, especifique o campo jwt_audience em address na seção x-google-backend. O valor do campo jwt_audience precisa ser o URL do serviço do Cloud Run. Exemplo:
```
...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...
```
Se o campo jwt_audience não estiver presente, a extensão x-google-backend usará o valor do campo address como padrão para a declaração de público do JWT. Isso poderá resultar em uma declaração de público-alvo JWT inesperada para o Cloud Run se o URL da tag de revisão for usado para address e nenhum jwt_audience for especificado
Digite o seguinte comando:
- CONFIG_ID especifica o nome da configuração da API;
- API_ID especifica o nome da sua API; Se a API ainda não existir, este comando a criará.
- PROJECT_ID é o nome do projeto do Google Cloud.
- SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens de back-ends com autenticação configurada. Para mais informações, consulte Como criar uma conta de serviço.
  Observação: a conta de serviço usada para criar uma configuração de API para um back-end do Cloud Run precisa ter o papel run.invoker atribuído.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Essa operação pode levar vários minutos para ser concluída conforme a configuração da API é propagada para os sistemas downstream. A criação de uma configuração de API complexa pode levar até dez minutos para ser concluída.
Depois que a configuração da API for criada, execute o comando a seguir para ver os detalhes:
```
gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID
```

Como implantar um gateway de API

Agora é possível implantar a API no gateway de API. A implantação de uma API no gateway de API também define um URL externo para os clientes da API acessarem sua API.

Execute o comando a seguir para implantar a configuração da API que você acabou de criar no gateway de API:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

onde:

GATEWAY_ID especifica o nome do gateway.
API_ID especifica o nome da API Gateway associada à API.
CONFIG_ID especifica o nome da configuração da API implantada no gateway;
GCP_REGION é a região do Google Cloud do gateway implantado.
Observação:
os valores permitidos são:
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
A compatibilidade com gateways de gateway de API criados em asia-east1 terminará em 1o de novembro de 2022. Revise todos os gateways em execução no asia-east1 e exclua ou recrie-os em um novo local conforme necessário.
PROJECT_ID é o nome do projeto do Google Cloud.

Após a conclusão, o comando a seguir pode exibir detalhes sobre o gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Observe o valor da propriedade defaultHostname na saída deste comando. Esta é a parte do nome do host do URL do gateway que você usará para testar a implantação na próxima etapa.

Como testar sua implantação de API

Agora é possível enviar solicitações para a API usando o URL gerado durante a implantação do gateway.

Digite o seguinte URL no navegador da Web, em que:

DEFAULT_HOSTNAME especifica a parte do nome do host do URL do gateway implantado.
hello é o caminho especificado nas configurações da API;

https://DEFAULT_HOSTNAME/hello

Exemplo:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Você verá o contêiner do Cloud Run executando o aplicativo no navegador.

Pronto. O gateway de API está gerenciando o acesso ao serviço de back-end do Cloud Run.

Como rastrear a atividade da API

Veja os gráficos de atividade da sua API na página Gateway da API no console do Google Cloud. Clique na sua API para ver os respectivos gráficos de atividade na página Visão geral. Talvez leve alguns instantes para a solicitação aparecer nos gráficos.
Verifique os registros de solicitações da API na página "Visualizador de registros". Há um link para a página Explorador de registros na página Gateway de API no console do Google Cloud.
Acessar a página "Gateway de API"
Na página "API Gateway", faça o seguinte
1. Selecione a API a ser visualizada.
2. Clique na guia Details.
3. Clique no link em Registros.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, faça o seguinte:

Como alternativa, também é possível excluir o projeto do Google Cloud usado neste tutorial.