Proteger o tráfego para um serviço com o console do Google Cloud

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 o console do Google Cloud. 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 Gateway de API e selecione ou crie um projeto do Google Cloud.

   Acessar a página "Gateway de API"

   Observação: se você não quiser manter os recursos criados usando este procedimento, crie um novo projeto em vez de selecionar um atual. Depois de concluir esses passos, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

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

   Caso ainda não tenha ativado esses serviços para o projeto selecionado, você receberá uma solicitação para fazer isso.

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

   Saiba como ativar o faturamento

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.

Observação :o nome real da função e do back-end no exemplo varia de acordo com a linguagem escolhida ao concluir o tutorial sobre as funções do Cloud Run. Este tutorial usa o exemplo do Node.js.

Como criar uma definição de API

A API Gateway usa uma definição de API para rotear chamadas para o serviço de back-end. É possível usar uma especificação OpenAPI que contenha anotações especializadas para definir o comportamento desejado do gateway de API. A OpenAPI especificação deste 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://us-central1-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Para usar a especificação OpenAPI mostrada acima para definir sua API:

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 (que será criado na próxima etapa) e optional-string por uma breve descrição da sua escolha. O valor desse campo é 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.
   2. No campo address, substitua PROJECT_ID pelo nome do seu projeto do Google Cloud.

Como criar um gateway

Agora você já pode criar e implantar um gateway no gateway de API.

1. Abra a página "Gateway de API" no console do Google Cloud.

   Acessar a página "Gateway de API"

2. Clique em Criar gateway.

3. Na seção API:

   1. É possível criar uma nova API ou selecionar uma atual na lista suspensa Selecionar uma API. Para este tutorial, selecione Criar uma nova API.
   2. Insira o Nome de exibição da sua API.
   3. Digite o ID da API.
   4. (Opcional) Adicione rótulos à API usando um formato de chave-valor. Para adicionar mais de um rótulo, clique em Adicionar rótulo e insira valores adicionais.

4. Na seção Configuração da API:

   1. É possível criar uma nova configuração de API ou selecionar uma existente na lista suspensa Selecionar uma configuração. Para este tutorial, selecione Criar uma nova configuração de API.
   2. Use o navegador de arquivos para fazer upload do openapi2-functions.yaml usado para definir a API.
   3. Insira um nome de exibição para sua configuração de API.

   4. Selecione uma conta de serviço na lista suspensa. A conta de serviço selecionada será usada como identidade para o gateway de API.

      Observação: se você não vir uma conta de serviço listada na lista suspensa, consulte Como configurar uma conta de serviço para garantir que uma conta de serviço esteja ativado para o projeto.

   5. (Opcional) Adicione rótulos à configuração da API usando um formato de chave-valor. Para adicionar mais de um rótulo, clique em Adicionar rótulo e insira valores adicionais.

5. Na seção Detalhes do gateway:

   1. Insira o nome de exibição do stream. O URL do gateway é gerado automaticamente.
   2. Selecione o local do gateway no menu suspenso.
   3. (Opcional) Adicione rótulos ao gateway usando um formato de chave-valor. Para adicionar mais de um rótulo, clique em Adicionar rótulo e insira valores adicionais.

6. Clique em Criar gateway.

Isso implanta a configuração da API em um gateway recém-criado. 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.

Isso pode levar vários minutos. Para verificar o status do processo de criação e implantação, clique no ícone Notificação na barra de navegação principal para exibir uma notificação de status, conforme mostrado na imagem abaixo:

Após a conclusão, você poderá ver os detalhes sobre o gateway na página de destino dos gateways.

Acessar a página "Gateways"

Anote o URL do gateway. Isso é usado para testar sua implantação na próxima etapa.

Observação: a exibição do URL do gateway recém-criado pode levar algum tempo. Se ela não aparecer instantaneamente, clique em Atualizar na página de destino "Gateways" para atualizar a tela.

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.

No navegador, digite o seguinte URL:

• GATEWAY_URL especifica o URL do gateway implantado.
• hello é o caminho especificado nas configurações da API;

https://GATEWAY_URL/hello

Exemplo:

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

A mensagem Hello World! será exibida no navegador.

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 a 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:
   1. No console do Google Cloud, acesse APIs e Serviços > Biblioteca.
   2. Na barra de pesquisa, digite o nome do serviço gerenciado da API que você acabou de criar. Esse valor pode ser encontrado na coluna Serviço gerenciado da API na página de destino das APIs. Exemplo:

      my-api-123abc456def1.apigateway.my-project.cloud.goog

   3. Na página de destino do serviço, clique em Ativar
      Observação: pode haver um atraso de até 30 minutos ou mais entre o momento em que a API é criada e o momento em que ela aparece na Biblioteca. Se a API não estiver visível na biblioteca, é possível ativá-lo usando a ferramenta de linha de comando gcloud. Digite o seguinte comando, em que MANAGED_SERVICE_NAME especifica o nome do serviço gerenciado da API:

      gcloud services enable MANAGED_SERVICE_NAME

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://us-central1.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. passado como um parâmetro de consulta chamado key ao solicitar acesso a todos os caminhos definidos na especificação.
3. Crie e implante uma nova configuração de API no gateway atual:
   1. Acesse a página de destino "Gateways".

      Acessar a página "Gateways"

   2. Selecione o gateway na lista para ver os detalhes.
   3. Clique em Editar para abrir o painel de configuração do gateway.
   4. Na seção Configuração da API:
      1. Selecione Criar uma configuração de API no menu suspenso disponível.
      2. Faça upload da especificação OpenAPI modificada usando o navegador de arquivos.
      3. Insira o nome de exibição da sua nova configuração de API.
      4. Selecione uma conta de serviço na lista suspensa. A conta de serviço selecionada será usada como a identidade do gateway de API.
      5. (Opcional) Adicione rótulos à configuração da API usando um formato de chave-valor. Para adicionar mais de um rótulo, clique em Adicionar rótulo e insira valores adicionais.
   5. Clique em Atualizar.

Como testar sua chave de API

Depois de criar e implantar a API modificada, faça uma solicitação a ela.

No navegador, digite o seguinte URL:

• GATEWAY_URL especifica o URL do gateway implantado.
• hello é o caminho especificado nas configurações da API;

https://GATEWAY_URL/hello

Exemplo:

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.

No navegador, digite o seguinte URL, em que:

• GATEWAY_URL especifica o URL do gateway implantado.
• hello é o caminho especificado nas configurações da API;
• API_KEY especifica a chave de API que você criou em Como proteger o acesso usando uma chave de API.

https://GATEWAY_URL/hello?key=API_KEY

Agora você verá Hello World! no navegador.

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.

Rastrear a atividade da API

1. Confira os gráficos de atividade da sua API na página Gateway de API na 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.

2. Verifique os registros de solicitações da API na página "Visualizador de registros". Um link para o A página Análise de registros pode ser encontrada na página Gateway de API na 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:

• Excluir gateways
• Excluir a API

Se preferir, exclua o projeto do Google Cloud usado neste tutorial.

A seguir

• Saiba mais sobre o gateway de API.
• Siga as etapas do guia de configuração do ambiente de desenvolvimento.