Usar chaves de API

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

Visão geral

Uma chave de API é uma string que identifica umGoogle Cloud projeto 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 da 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 gateway de API 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.

Criar uma chave de API

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

Ir para Credenciais

Configurar a autenticação de chave de API para o gateway de API

Configure a autenticação de chave de API para o gateway de API para proteger o acesso ao gateway usando uma chave de API, conforme descrito nas seções a seguir.

  1. Ative o suporte à chave de API para seu serviço.

    Console doGoogle Cloud

    Faça o seguinte:

    1. No console do Google Cloud , acesse APIs e serviços > Biblioteca.

      Acessar a biblioteca de APIs e serviços

    2. Na barra de pesquisa, digite o nome do serviço gerenciado da API. 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. Clique no card do serviço para abrir a página de destino.
    4. Na página de destino do serviço, clique em Ativar

    CLI do Google Cloud

    Digite o seguinte comando, em que 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.

    gcloud services enable MANAGED_SERVICE_NAME

    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:
  backends:
    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 da 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.

Usar chaves 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.

Por exemplo, é possível transmiti-lo usando o parâmetro de consulta key em uma chamada de curl, da seguinte maneira:

https://GATEWAY_URL/hello?key=API_KEY