Usar chaves da API

Esta página descreve como usar chaves da API no API Gateway.

Uma chave de API é uma string que identifica um Google Cloud projeto para fins de quota, faturação e monitorização. Os programadores geram uma chave da API num projeto na Google Cloud consola. Em seguida, incorporam essa chave em cada chamada à sua API como um parâmetro de consulta ou num cabeçalho de pedido.

Se especificar um requisito de chave de API na configuração da API, o API Gateway usa a chave de API para procurar o Google Cloud projeto associado. O API Gateway rejeita pedidos, a menos que a chave da API tenha sido gerada no seu Google Cloud projeto ou noutrosGoogle Cloud projetos nos quais a sua API tenha sido ativada.

Para criar uma chave da API ou ver as chaves da API já disponíveis no seu Google Cloud projeto, aceda à página APIs e serviços > Credenciais.

Aceder a Credenciais

Use uma chave da API

Para usar funcionalidades do API Gateway, como quotas, pode transmitir uma chave de API para que o API Gateway possa identificar o Google Cloud projeto ao qual a aplicação cliente está associada.

Configure a autenticação de chaves de API para o API Gateway

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

  1. Ative o suporte de chaves da API para o seu serviço. Introduza o seguinte comando, em que:
    • MANAGED_SERVICE_NAME especifica o nome do serviço gerido criado quando implementou a API. Pode ver esta propriedade de serviço gerido apresentada com o comando gcloud api-gateway apis describe.
    • PROJECT_ID especifica o nome do seu Google Cloud projeto.
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     Por 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 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 tipo security e securityDefinitions ou 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://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 a sua API para exigir uma chave de API transmitida como um parâmetro de consulta denominado key quando pede 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 de API transmitida como um parâmetro de consulta denominado key quando solicita acesso a todos os caminhos definidos na especificação.
  3. Crie uma nova configuração de API com a descrição OpenAPI modificada através do 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
     Por exemplo: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. Execute o seguinte comando para atualizar o gateway existente com a nova configuração da API: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GATEWAY_LOCATION --project=PROJECT_ID
     Por exemplo: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Restringir chaves da API

Por predefinição, as chaves da API não têm restrições, o que as torna vulneráveis a utilização não autorizada. Adicione restrições de API sempre que possível. As restrições da API especificam que APIs podem ser chamadas através da chave da API. Todas as chaves da API usadas por aplicações de produção devem ter restrições da API.

Para adicionar restrições de API:

  1. Encontre o título da API, conforme indicado na configuração da API. No exemplo seguinte, o título da API é My Example Config:

    OpenAPI 2.0

    # openapi.yaml
swagger: '2.0'
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

    OpenAPI 3.x

    # openapi.yaml
openapi: 3.0.4
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

  2. Na Google Cloud consola, aceda à página APIs e serviços > Credenciais.

    Aceder a Credenciais

  3. Selecione o nome da chave da API que quer usar para a sua API.

  4. Na secção Restrições da API da página de detalhes da chave da API, clique em Restringir chave.

  5. Selecione a API que a sua chave de API vai usar para aceder a partir da lista pendente de APIs disponíveis. Por exemplo, selecione My Example Config.

  6. Clique em Guardar.

A restrição deve entrar em vigor dentro de momentos.