Proteger o tráfego para 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 API e acessar um serviço de back-end no Cloud Functions 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

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

  2. Confirme se o faturamento está ativado no projeto.

    Saiba como ativar o faturamento

  3. Verifique se a Google Cloud CLI foi transferida por download e instalada na máquina.

    Fazer o download da CLI gcloud

  4. Atualize os componentesgcloud:

    gcloud components update

  5. 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 Título
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 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 as chamadas recebidas para um back-end do Cloud Function 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 do Cloud Functions e implantar o serviço de back-end.

Como criar uma API

Agora você já pode criar sua API no gateway de API.

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

  2. 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 OpenAPI usada neste guia de início rápido contém instruções de roteamento para o back-end do Cloud Functions:

# 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 e criar uma configuração de API usando a CLI gcloud:

  1. Na linha de comando, crie um novo arquivo chamado openapi2-functions.yaml.

  2. Copie e cole o conteúdo da especificação OpenAPI mostrado acima no arquivo recém-criado.

  3. Edite o arquivo da seguinte forma:

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

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

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

  1. 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.
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
    Exemplo: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. 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 e securityDefinitions, como mostrado abaixo: 
      # 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"
    O securityDefinition configura sua API para exigir uma chave de API passada como um parâmetro de consulta chamado key ao solicitar acesso a todos os caminhos definidos na especificação.
  3. Crie uma nova configuração de API com a especificação OpenAPI modificada usando o seguinte comando: 
    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
    Exemplo: 
    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
  4. Execute o seguinte comando para atualizar o gateway atual com a nova configuração de API: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID
    Exemplo: 
    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:

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

A seguir