Como usar chaves de API

Nesta página, descrevemos como usar chaves de API no API Gateway.

Uma chave de API é uma string que identifica um projetoGoogle Cloud para fins de cota, faturamento e monitoramento. Os desenvolvedores geram uma chave de API em um projeto no console do Google Cloud . Em seguida, eles incorporam essa chave em todas as chamadas para sua API como um parâmetro de consulta ou em um cabeçalho de solicitação.

Se você especificar um requisito de chave de API na configuração da API, o gateway de API usará a chave de API para procurar o projeto Google Cloud associado. O API Gateway rejeita solicitações, a menos que a chave de API tenha sido gerada no seu projeto Google Cloud ou em outros projetosGoogle Cloud em que a API foi ativada.

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

Ir para Credenciais

Usar uma chave de API

Para usar recursos do gateway de API, como cotas, é possível passar uma chave de API para que o gateway de API possa identificar o projeto Google Cloud ao qual o aplicativo cliente está associado.

Configurar a autenticação de chave de API para o gateway 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 api-gateway apis describe.
    • PROJECT_ID especifica o nome do seu projeto 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 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 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.

    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 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 configuração de API com a descriçã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
     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 atual com a nova configuração de API: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GATEWAY_LOCATION --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

Restringir chaves de API

Por padrão, as chaves de API não têm restrições, o que as torna vulneráveis a uso não autorizado. Adicione restrições de API sempre que possível. Essas restrições especificam quais APIs podem ser chamadas com a chave de API. Todas as chaves de API usadas por aplicativos de produção precisam ter restrições de API.

Para adicionar restrições de API:

  1. Encontre o título da API, conforme indicado na configuração da API. No exemplo a seguir, 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. No console Google Cloud , acesse a página APIs e serviços > Credenciais.

    Ir para Credenciais

  3. Selecione o nome da chave de API que você quer usar para sua API.

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

  5. Selecione na lista suspensa de APIs disponíveis aquela que sua chave de API vai usar para acessar. Por exemplo, selecione My Example Config.

  6. Clique em Salvar.

Sua restrição vai entrar em vigor em alguns instantes.