Esta página foi traduzida pela API Cloud Translation.

Início rápido: proteja o tráfego para um serviço com a Google Cloud consola

Esta página mostra como implementar uma API no API Gateway para proteger o tráfego para um serviço de back-end.

Siga os passos para implementar uma nova API para aceder a um serviço de back-end nas funções do Cloud Run através da Google Cloud consola. Este início rápido também descreve como usar uma chave da API para proteger o seu back-end contra acesso não autorizado.

Antes de começar

Na Google Cloud consola, aceda à página API Gateway.

Aceda ao API Gateway

Nota: se não planeia manter os recursos que criar neste início rápido, crie um novo projeto em vez de selecionar um projeto existente. Depois de concluir estes passos, pode eliminar o projeto, removendo todos os recursos associados ao mesmo.
O API Gateway requer que ative os seguintes serviços Google:

Nome Título

apigateway.googleapis.com API do API Gateway

servicemanagement.googleapis.com Service Management API

servicecontrol.googleapis.com Service Control API

Se não tiver ativado anteriormente estes serviços para o projeto que selecionar, é-lhe pedido que o faça.
Confirme se a faturação está ativada para o seu projeto.
Saiba como ativar a faturação

Nome	Título
`apigateway.googleapis.com`	API do API Gateway
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

Implemente um back-end de API

O API Gateway está posicionado à frente de um serviço de back-end implementado e processa todos os pedidos recebidos. Neste início rápido, o API Gateway encaminha as chamadas recebidas para um back-end de função do Cloud Run denominado helloGET que contém a função apresentada da seguinte forma:

/**
 * 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 os passos no Início rápido: usar a CLI Google Cloud para transferir o código de exemplo das funções do Cloud Run e implementar o serviço de back-end da função do Cloud Run.

Crie uma configuração de API

O API Gateway usa uma configuração da API para encaminhar chamadas para o serviço de back-end. Pode usar uma especificação OpenAPI que contenha extensões especializadas para definir o comportamento do gateway de API escolhido. Para mais detalhes sobre as extensões OpenAPI suportadas, consulte o seguinte:

A especificação OpenAPI para este início rápido contém instruções de encaminhamento para o back-end da função do Cloud Run:

OpenAPI 2.0

# openapi-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://GATEWAY_LOCATION -PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      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: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

Use esta especificação da OpenAPI para definir a sua API:

Na linha de comandos, crie um novo ficheiro com o nome openapi-functions.yaml.
Copie e cole o conteúdo da especificação OpenAPI apresentada no exemplo anterior no ficheiro recém-criado.
Edite o ficheiro da seguinte forma:
1. No campo title, substitua API_ID pelo nome da sua API (que cria no passo seguinte) e substitua optional-string por uma breve descrição à sua escolha. O valor deste campo é usado quando são geradas chaves de API que concedem acesso a esta API. Consulte os requisitos de ID da API para ver as diretrizes de nomenclatura de IDs da API.
2. No campo address, substitua PROJECT_ID pelo nome do seu Google Cloud projeto e substitua GATEWAY_LOCATION pelo Google Cloud onde a gateway está implementada.

Crie um gateway

Agora, tem tudo pronto para criar e implementar um gateway no API Gateway.

Abra a página do API Gateway na Google Cloud consola.

Aceda ao API Gateway
Clique em Criar gateway.
Na secção API:
1. Opte por criar uma nova API ou selecionar uma API existente no menu pendente Selecionar uma API. Para este tutorial, selecione Criar uma nova API.
2. Introduza o Nome a apresentar da sua API.
3. Introduza o ID da API da sua API.
4. (Opcional) Adicione etiquetas à sua API através de um formato chave:valor. Para adicionar mais de uma etiqueta, clique em Adicionar etiqueta e introduza valores adicionais.
Na secção Configuração da API:
1. Opte por criar uma nova configuração da API ou selecionar uma configuração da API existente no menu pendente Selecionar uma configuração. Para este tutorial, selecione Criar uma nova configuração da API.
2. Use o explorador de ficheiros para carregar o openapi-functions.yaml usado para definir a sua API.
3. Introduza um nome a apresentar para a configuração da API.
4. Selecione uma conta de serviço na lista pendente. A conta de serviço que selecionar é usada como identidade para o API Gateway.
  
  Nota: se não vir uma conta de serviço apresentada no menu pendente, consulte o artigo Configurar uma conta de serviço para verificar se uma conta de serviço está ativada para o seu projeto.
5. (Opcional) Adicione etiquetas à configuração da API através de um formato de chave:valor. Para adicionar mais do que uma etiqueta, clique em Adicionar etiqueta e introduza valores adicionais.
Na secção Detalhes da gateway:
1. Introduza o nome a apresentar da gateway. O URL para o gateway é gerado automaticamente.
2. Selecione a localização da entrada no menu pendente.
3. (Opcional) Adicione etiquetas ao seu gateway através de um formato chave:valor. Para adicionar mais de uma etiqueta, clique em Adicionar etiqueta e introduza valores adicionais.
Clique em Criar gateway.

Esta ação implementa a configuração da API num gateway recém-criado. A implementação de uma configuração da API num gateway define um URL externo que os clientes da API podem usar para aceder à sua API.

A operação pode demorar vários minutos a ser concluída. Para verificar o estado do processo de criação e implementação, clique no ícone Notificação na barra de navegação principal para apresentar uma notificação de estado, conforme mostrado na imagem seguinte:

Painel de notificações para notificações de estado

Após a conclusão com êxito, pode ver detalhes sobre a entrada na página de destino Entradas.

Aceda ao API Gateway

Tome nota do URL do gateway. Vai usá-lo para testar a implementação no passo seguinte.

Teste a implementação da API

Agora, pode enviar pedidos para a sua API através do URL gerado após a implementação da gateway.

No navegador, introduza o seguinte URL, em que:

GATEWAY_URL especifica o URL do gateway implementado.
hello é o caminho especificado na configuração da API.

https://GATEWAY_URL/hello

Por exemplo:

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

A mensagem Hello World! deve ser apresentada no navegador.

Criou e implementou um gateway de API com êxito!

Acesso seguro com uma chave da API

Para proteger o acesso ao seu back-end da API, gere uma chave da API associada ao seu projeto e conceda a essa chave acesso para chamar a sua API. Consulte o artigo Restringir o acesso à API com chaves da API para mais informações.

Se ainda não tiver uma chave da API associada ao Google Cloud projeto que está a usar neste início rápido, adicione uma seguindo os passos em Criar uma chave da API.

Para proteger o acesso ao seu gateway através de uma chave da API:

Ative o suporte de chaves de API para o seu serviço:
1. Na Google Cloud consola, aceda a APIs e serviços > Biblioteca.
2. Na barra de pesquisa, introduza o nome do serviço gerido da API que acabou de criar. Pode encontrar este valor na coluna Serviço gerido da sua API na página de destino das APIs. Por exemplo:
```
my-api-123abc456def1.apigateway.my-project.cloud.goog
```
3. Na página de destino do seu serviço, clique em Ativar.
  Nota: pode haver um atraso de até 30 minutos ou mais entre o momento em que cria a API e o momento em que aparece na biblioteca. Se a sua API não estiver visível na biblioteca, pode ativá-la através da ferramenta de linha de comandos gcloud. Introduza o seguinte comando, em que MANAGED_SERVICE_NAME especifica o nome do serviço gerido da sua API:
```
gcloud services enable MANAGED_SERVICE_NAME
```

Modifique a especificação OpenAPI usada para criar a configuração da API de modo a incluir instruções para aplicar uma política de segurança de validação de chaves da API a todo o tráfego. Adicione o security tipo e securitySchemes, conforme mostrado:

OpenAPI 2.0

  # 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://GATEWAY_LOCATION-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 a sua API para exigir uma chave da API transmitida como um parâmetro de consulta denominado key quando solicita acesso a todos os caminhos definidos na especificação.

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      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: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

O securitySchemes configura a sua API para exigir uma chave da API transmitida como um parâmetro de consulta denominado key quando solicita acesso a todos os caminhos definidos na especificação.

Crie e implemente uma nova configuração de API no seu gateway existente:
1. Aceda à página de destino Gateways.
  
  Aceda ao API Gateway
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 secção Configuração da API:
  1. Selecione Criar uma nova configuração de API no menu pendente disponível.
  2. Carregue a especificação OpenAPI modificada através do explorador de ficheiros.
  3. Introduza o nome a apresentar da nova configuração da API.
  4. Selecione uma conta de serviço na lista pendente. A conta de serviço que selecionar é usada como identidade para o API Gateway.
  5. (Opcional) Adicione etiquetas à configuração da API através de um formato de chave/valor. Para adicionar mais do que uma etiqueta, clique em Adicionar etiqueta e introduza valores adicionais.
5. Clique em Atualizar.

Teste a chave da API

Depois de criar e implementar a API modificada, experimente fazer um pedido à mesma.

No navegador, introduza o seguinte URL, em que:

GATEWAY_URL especifica o URL do gateway implementado.
hello é o caminho especificado na configuração da API.

https://GATEWAY_URL/hello

Isto deve 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, no navegador, introduza o seguinte URL, onde:

GATEWAY_URL especifica o URL do gateway implementado.
hello é o caminho especificado na configuração da API.
API_KEY especifica a chave da API que criou em Proteger o acesso através de uma chave da API.

https://GATEWAY_URL/hello?key=API_KEY

Agora, deve ver a app Hello World! no seu navegador.

Parabéns! Protegeu com êxito o back-end da API com um API Gateway. Agora, pode começar a integrar novos clientes da API gerando chaves da API adicionais.

Acompanhe a atividade da API

Veja os gráficos de atividade da sua API na página API Gateway na Google Cloud consola. Clique na sua API para ver os respetivos gráficos de atividade na página Vista geral. Os pedidos podem demorar alguns momentos a refletir-se nos gráficos.
Consulte os registos de pedidos da sua API na página Explorador de registos. Pode encontrar um link para a página do Explorador de registos na página do API Gateway na Google Cloud consola.

Aceda ao API Gateway

Depois de aceder à página do API Gateway:
1. Selecione a API para ver.
2. Clique no separador Detalhes.
3. Clique no link em Registos.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste início rápido, pode:

Em alternativa, também pode eliminar o Google Cloud projeto usado para este tutorial.

O que se segue?

Saiba mais acerca do API Gateway
Siga as instruções em Configurar o ambiente de programação