Proteger o tráfego de um serviço com a CLI gcloud
Nesta página, mostramos como implantar uma API no gateway de API para proteger o tráfego em um serviço de back-end.
Siga as etapas abaixo para implantar uma nova API e acessar um serviço de back-end nas funções do Cloud Run usando a Google Cloud CLI. Neste guia de início rápido, também descrevemos como usar uma chave de API para proteger o back-end contra acessos não autorizados.
Antes de começar
No console do Google Cloud, acesse a página Painel e selecione ou crie um projeto do Google Cloud.
Confirme se o faturamento está ativado no projeto.
Faça o download e instale a Google Cloud CLI na sua máquina.
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
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 implantar um back-end de API
O gateway de API fica na frente de um serviço de back-end implantado e processa todas as solicitações recebidas. Neste guia de início rápido, o gateway de API encaminha chamadas de entrada para um back-end de função do Cloud Run chamado helloGET
, que contém a função mostrada abaixo:
/** * HTTP Cloud Function. * This function is exported by index.js, and is executed when * you make an HTTP request to the deployed function's endpoint. * * @param {Object} req Cloud Function request context. * More info: https://expressjs.com/en/api.html#req * @param {Object} res Cloud Function response context. * More info: https://expressjs.com/en/api.html#res */ exports.helloGET = (req, res) => { res.send('Hello World!'); };
Siga as etapas em Guia de início rápido: como usar a Google Cloud CLI para fazer o download do código de amostra das funções do Cloud Run e implantar o serviço de back-end da função do Cloud Run.
Como criar uma API
Agora você já pode criar sua API no gateway de API.
Digite o seguinte comando, em que:
- API_ID especifica o nome da sua API; Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura.
- PROJECT_ID é o nome do projeto do Google Cloud.
gcloud api-gateway apis create API_ID --project=PROJECT_ID
Exemplo:
gcloud api-gateway apis create my-api --project=my-project
Após a conclusão, o comando a seguir pode ser usado para ver detalhes sobre a nova API:
gcloud api-gateway apis describe API_ID --project=PROJECT_ID
Exemplo:
gcloud api-gateway apis describe my-api --project=my-project
Este comando mostra o seguinte:
createTime: '2020-02-29T21:52:20.297426875Z' displayName: my-api managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog name: projects/my-project/locations/global/apis/my-api state: ACTIVE updateTime: '2020-02-29T21:52:20.647923711Z'
Observe o valor da propriedade managedService
. Esse valor é usado para ativar a API em uma etapa subsequente.
Como criar uma configuração de API
Antes de usar o gateway de API para gerenciar o tráfego para o back-end da API 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. A especificação da OpenAPI usada neste guia de início rápido contém instruções de roteamento para o back-end da função do Cloud Run:
# openapi2-functions.yaml swagger: '2.0' info: title: API_ID optional-string description: Sample API on API Gateway with a Google Cloud Functions backend version: 1.0.0 schemes: - https produces: - application/json paths: /hello: get: summary: Greet a user operationId: hello x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET responses: '200': description: A successful response schema: type: string
Para fazer upload dessa especificação OpenAPI e criar uma configuração de API usando a gcloud CLI:
Na linha de comando, crie um novo arquivo chamado
openapi2-functions.yaml
.Copie e cole o conteúdo da especificação OpenAPI mostrado acima no arquivo recém-criado.
Edite o arquivo da seguinte forma:
- No campo
title
, substitua API_ID pelo nome da API e optional-string por uma breve descrição de sua escolha. O valor desse campo é usado ao produzir chaves de API que concedem acesso a essa API. - No campo
address
, substitua GCP_REGION pela região do GCP da função implantada e PROJECT_ID pelo nome do seu projeto do Google Cloud.
- No campo
Digite o seguinte comando, em que:
- CONFIG_ID especifica o nome da configuração da API;
- API_ID especifica o nome da sua API;
- API_DEFINITION especifica o nome do arquivo da especificação OpenAPI.
- 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 configurar uma conta de serviço.
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
Exemplo:
gcloud api-gateway api-configs create my-config \ --api=my-api --openapi-spec=openapi2-functions.yaml \ --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
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
Exemplo:
gcloud api-gateway api-configs describe my-config \ --api=my-api --project=my-project
A saída mostra os detalhes de configuração da API, incluindo o nome e o estado, conforme mostrado no exemplo abaixo.
createTime: '2020-02-07T18:17:01.839180746Z' displayName: my-config gatewayConfig: backendConfig: googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com name: projects/my-project/locations/global/apis/my-api/configs/my-config serviceRollout: rolloutId: 2020-02-07r0 state: ACTIVE updateTime: '2020-02-07T18:17:02.173778118Z'
Como criar um gateway
Agora implante a configuração da API em um gateway. A implantação de uma configuração de API em um gateway define um URL externo que os clientes da API podem usar para acessar 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.
PROJECT_ID é o nome do projeto do Google Cloud.
Exemplo:
gcloud api-gateway gateways create my-gateway \ --api=my-api --api-config=my-config \ --location=us-central1 --project=my-project
Após a conclusão, use o seguinte comando para ver os detalhes do gateway:
gcloud api-gateway gateways describe GATEWAY_ID \ --location=GCP_REGION --project=PROJECT_ID
Exemplo:
gcloud api-gateway gateways describe my-gateway \ --location=us-central1 --project=my-project
Este comando mostra o seguinte:
apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config createTime: '2020-02-05T13:44:12.997862831Z' defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev displayName: my-gateway name: projects/my-project/locations/us-central1/gateways/my-gateway serviceAccount: email: 0000000000000-compute@developer.gserviceaccount.com state: ACTIVE updateTime: '2020-02-05T13:45:00.844705087Z'
Observe o valor da propriedade defaultHostname
. 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 comando curl
, 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;
curl https://DEFAULT_HOSTNAME/hello
Exemplo:
curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello
A saída é:
Hello World!
Você criou e implantou um gateway de API.
Como proteger o acesso usando uma chave de API
Para proteger o acesso ao back-end da API, gere uma chave associada ao seu projeto e conceda acesso para chamar sua API. 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 do Google Cloud que está usando neste guia de início rápido, adicione uma seguindo as etapas em Criar uma chave de API.
Para proteger o acesso ao gateway usando uma chave de API:
- Ative o suporte à chave de API para seu serviço. Digite o seguinte comando:
- MANAGED_SERVICE_NAME especifica o nome do serviço gerenciado criado quando você implantou a API. Isso pode ser visualizado na propriedade de serviço gerenciado listada com o comando
gcloud apigee-gateway apis describe
. - PROJECT_ID é o nome do projeto do Google Cloud.
Exemplo:gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
- MANAGED_SERVICE_NAME especifica o nome do serviço gerenciado criado quando você implantou a API. Isso pode ser visualizado na propriedade de serviço gerenciado listada com o comando
- Modifique a especificação OpenAPI usada para criar a configuração da API e inclua instruções para aplicar uma política de segurança de validação de chave de API a todo o tráfego. Adicione o tipo
security
esecurityDefinitions
, como mostrado abaixo: O# openapi2-functions.yaml swagger: '2.0' info: title: API_ID optional-string description: Sample API on API Gateway with a Google Cloud Functions backend version: 1.0.0 schemes: - https produces: - application/json paths: /hello: get: summary: Greet a user operationId: hello x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET security: - api_key: [] responses: '200': description: A successful response schema: type: string securityDefinitions: # This section configures basic authentication with an API key. api_key: type: "apiKey" name: "key" in: "query"
securityDefinition
configura a API para exigir uma chave de API transmitida como um parâmetro de consulta chamadokey
ao solicitar acesso a todos os caminhos definidos na especificação. - Crie uma nova configuração de API com a especificação OpenAPI modificada usando o seguinte comando:
Por exemplo:gcloud api-gateway api-configs create NEW_CONFIG_ID \ --api=API_ID --openapi-spec=NEW_API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
gcloud api-gateway api-configs create my-config-key \ --api=my-api --openapi-spec=openapi2-functions.yaml \ --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
- Execute o seguinte comando para atualizar o gateway atual com a nova configuração de API:
Exemplo:gcloud api-gateway gateways update GATEWAY_ID \ --api=API_ID --api-config=NEW_CONFIG_ID \ --location=GCP_REGION --project=PROJECT_ID
gcloud api-gateway gateways update my-gateway \ --api=my-api --api-config=my-config-key \ --location=us-central1 --project=my-project
Como testar sua chave de API
Depois de criar e implantar a API modificada, faça uma solicitação a ela.
Digite o seguinte comando curl
, 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;
curl https://DEFAULT_HOSTNAME/hello
Exemplo:
curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello
Isso deverá resultar no seguinte erro:
UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.
Agora, digite o seguinte comando curl
, 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;- API_KEY especifica a chave de API criada na etapa anterior;
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY
Agora você verá Hello World!
na resposta da sua API.
Parabéns! Você protegeu seu back-end da API com um gateway de API. Agora você pode começar a integrar novos clientes de API gerando chaves de API adicionais.
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:
Também é possível excluir o projeto do Google Cloud usado neste tutorial.
A seguir
- Saiba mais sobre o gateway de API.
- Leia Como configurar o ambiente de desenvolvimento.
- Saiba mais sobre a autenticação entre serviços.