Como criar e gerenciar chaves de API

Esta página explica como criar e gerenciar chaves de API usando a API API Keys.

Para saber como usar uma chave de API com suas chamadas para APIs do Google Cloud , consulte Como usar chaves de API.

Criar chave de API

É possível criar uma chave de API usando o método CreateKey. O método requer um parâmetro Key. Só é possível especificar os campos displayName e restrictions do objeto Key. O CreateKey não é um método síncrono. Em vez disso, quando você faz uma chamada para CreateKey, inicia uma operação de longa duração. O exemplo a seguir emite uma chamada CreateKey para criar uma chave de API sem restrições:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

Se for bem-sucedido, o método vai retornar uma operação de longa duração na resposta. Conforme descrito em Como pesquisar operações de longa duração, você faz repetidamente chamadas operations.get com o valor do campo name. Quando a resposta de operations.get contém "done": true, o objeto response contém um Key, semelhante a este:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

No objeto response:

  • O campo name contém um identificador exclusivo da chave de API. Use o valor no campo name nos outros métodos que exigem um nome de chave. Esse valor não é exibido no console do Google Cloud , mas você pode chamar o método ListKeys para receber o names de todas as suas chaves de API. O campo Key.name está sempre no seguinte formato: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • O campo displayName é mapeado para o campo Name no consoleGoogle Cloud . Por isso, talvez seja necessário fornecer um displayName ao chamar CreateKey.
  • O campo keyString contém a string que você envia para as APIs que exigem uma chave de API. O keyString é mapeado para o campo API key no consoleGoogle Cloud . Você pode chamar o método GetKeyString para receber o keyString de uma chave de API.
  • O campo etag contém um checksum calculado pelo servidor com base no valor atual da chave. Transmita o valor etag ao chamar os métodos UpdateKey e DeleteKey.

ID da chave especificado pelo usuário

É possível especificar um keyId como um parâmetro de consulta para o método CreateKey. Quando especificado, o valor se torna o componente final do Key.name.

Por exemplo, considere a seguinte chamada para CreateKey:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key with user-specified ID"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1'

Para este exemplo, o campo Key.name tem o seguinte valor:

"name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

Atualizar o nome de exibição

Para mudar o displayName de uma chave de API ou adicionar um displayName a uma chave criada sem um, chame o método UpdateKey. Ao chamar UpdateKey, você inicia uma operação de longa duração que atualiza a chave.

O exemplo a seguir ilustra como chamar UpdateKey:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName": "New display name",
          "etag" : "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName'

Quando a resposta de operations.get contém "done": true, o response contém um objeto Key com o displayName atualizado.

Excluir uma chave de API

Para excluir uma chave de API, use o método DeleteKey. Ao chamar DeleteKey, você inicia uma operação de longa duração que marca a chave como DELETED.

O exemplo a seguir ilustra como chamar DeleteKey:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H 'If-Match: "ETAG"' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID'

Quando a resposta de operations.get contém "done": true, o response é semelhante a este:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Uma chave de API marcada como DELETED não pode ser usada, mas também não é completamente removida do nosso sistema. Para listar as chaves de API que ainda existem, mas estão marcadas como DELETED, defina show_deleted como "true" para o método ListKeys:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true'

Após 30 dias, a chave de API é excluída permanentemente.

Restaurar uma chave de API

Para restaurar uma chave de API antes que ela seja excluída permanentemente, chame o método UndeleteKey. Ao chamar UndeleteKey, você inicia uma operação de longa duração que marca a chave como ACTIVE.

O exemplo a seguir ilustra como chamar UndeleteKey:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete'

A seguir