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 Google Cloud projeto.
- 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 usando 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 Google Cloud console, acesse a página Painel e selecione ou crie um Google Cloud projeto.
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 de projeto é chamado de PROJECT_ID.
Faça o download e instale a CLI do Google Cloud.
Atualize os componentes
gcloud
:gcloud components update
Defina o projeto padrão. Substitua PROJECT_ID pelo ID do Google Cloud projeto.
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 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 | Nome |
---|---|
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.comgcloud 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 escolhido 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 à especificação da 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 arquivoopenapi2-run.yaml
, conforme mostrado no exemplo 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 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
na seçãox-google-backend
, substitua APP_URL pelo URL real do seu serviço do Cloud Run (o caminho completo da API chamada). Exemplo:https://hello-abc1def2gh-uc.a.run.app
. - 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 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.
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ãoGoogle Cloud do gateway implantado.
PROJECT_ID especifica o nome do projeto 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 está gerenciando o acesso ao serviço de back-end do Cloud Run.
Rastrear a atividade da API
Confira os gráficos de atividade da API na página Gateway de API no consoleGoogle Cloud . Clique na sua API para conferir 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". O link para a página do Explorador de registros pode ser encontrado na página do Gateway de API no consoleGoogle Cloud .
Na página "API Gateway", faça o seguinte
- 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 Google Cloud projeto usado neste tutorial.