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 Cloud de Confiance by S3NS , consulte Como usar chaves de API.

Antes de começar

A página usa curl e a Google Cloud CLI para enviar solicitações à API Keys. Consulte Como começar a usar as chaves de API para saber como se preparar para testar a 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, ao emitir uma chamada para CreateKey, você 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:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

Se for bem-sucedido, o método vai retornar uma operação de longa duração na resposta. Conforme descrito em Pesquisa de operações de longa duração, você faz chamadas operations.get repetidamente 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. Você usa o valor no campo name nos outros métodos que exigem um nome de chave. Esse valor não é exibido no console do Cloud de Confiance , mas você pode chamar o método ListKeys para receber o names de todas as suas chaves de API. O campo Key.name sempre está no seguinte formato: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • O campo displayName é mapeado para o campo Name no consoleCloud de Confiance . Por isso, talvez seja interessante 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 consoleCloud de Confiance . 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:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

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:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName -X PATCH -d '{"displayName": "New display name", "etag" : "ETAG"}'

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:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

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

{
  "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:

gcurl 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:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

A seguir