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.
- Crie ou selecione 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 descrição da OpenAPI que descreva sua API e configure as rotas para o serviço de back-end do Cloud Run. Consulte Como criar uma configuração de API.
- Implante um gateway de API usando a configuração da API. Consulte Como implantar um gateway de API.
- Rastrear a atividade para seus serviços. Consulte Como rastrear a atividade da API.
- Para evitar 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 .
Verifique se o faturamento foi ativado para o projeto.
Anote o ID do projeto que você quer usar neste tutorial. No restante desta página, esse ID do projeto é chamado de PROJECT_ID.
Faça o download e instale a Google Cloud CLI.
Atualize os componentes
gcloud: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 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 o URL do aplicativo, a região e o ID do projeto em que seus aplicativos são implantados.
Ativar serviços obrigatórios
O gateway de API exige que você ative os seguintes serviços do Google Cloud :
| Nome | Nome do serviço |
|---|---|
| API Gateway API | apigateway.googleapis.com |
| API Service Management | servicemanagement.googleapis.com |
| API Service Control | servicecontrol.googleapis.com |
Para ativar os serviços necessários:
Console do Google Cloud
No console do Google Cloud , acesse a página APIs e serviços > Biblioteca de APIs.
- Na página Biblioteca de APIs, digite o nome da API necessária na barra de pesquisa.
- Nos resultados da pesquisa, selecione a página da API.
- Na página da API, clique em Ativar.
- Repita essas etapas para cada um dos serviços listados na tabela anterior.
CLI do Google Cloud
Use os seguintes comandos para ativar os serviços:
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
Para mais informações sobre os serviços do gcloud, consulte
serviços gcloud.
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.
É possível criar uma configuração de API usando uma descrição da OpenAPI que contenha anotações especializadas para definir o comportamento escolhido do gateway de API. Você precisará adicionar um campo específico do Google que contenha o URL de cada app do Cloud Run para que o gateway de API tenha as informações necessárias para invocar um app.
Para mais detalhes sobre as extensões da OpenAPI compatíveis, consulte:
Para criar a configuração da API:
- Crie um arquivo de texto chamado
openapi-run.yaml. Para facilitar, esta página se refere à descrição da OpenAPI por esse nome de arquivo, mas você pode usar outro nome, se preferir. - Copie o conteúdo do arquivo a seguir para o arquivo
openapi-run.yaml:OpenAPI 2.0
# openapi-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 campotitleé 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
addressda seçãox-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.
OpenAPI 3.x
# openapi-run.yaml openapi: 3.0.4 info: title: API_ID optional-string description: Sample API on API Gateway with a Cloud Run backend version: 1.0.0 # Define reusable components in x-google-api-management x-google-api-management: backends: cloudrun_backend: address: APP_URL deadline: 30.0 pathTranslation: APPEND_PATH_TO_ADDRESS protocol: "http/1.1" # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden. 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
- 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 campotitleé 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, substitua APP_URL pelo URL real do serviço do Cloud Run (o caminho completo da API chamada). Por exemplo:https://hello-687541448612.us-central1.run.app.
- No campo
- 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 especifica o nome do projeto do Google Cloud .
- SERVICE_ACCOUNT_EMAIL especifica a conta de serviço usada para assinar tokens para back-ends com autenticação configurada. Para mais informações, consulte Como criar uma conta de serviço.
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
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 do gateway de API associada a esse gateway.
- CONFIG_ID especifica o nome da configuração da API implantada no gateway;
GCP_REGION é a região doGoogle Cloud do gateway implantado.
PROJECT_ID especifica 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.
Testar a implantação da 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-687541448612.us-central1.run.app/hello
Você verá o contêiner do Cloud Run executando o aplicativo no navegador.
Pronto. Seu gateway está gerenciando o acesso ao serviço de back-end do Cloud Run.
Rastrear a atividade da API
Veja os gráficos de atividade da API na página gateway de API no console doGoogle Cloud . Clique na API para ver os 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". Um link para a página da Análise de Registros pode ser encontrado na página do gateway de API no console doGoogle Cloud .
Na página do gateway de API:
- Selecione a API a ser visualizada.
- Clique na guia Details.
- 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, você também pode excluir o projeto do Google Cloud usado neste tutorial.