Como criar e gerenciar chaves de API

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

Para informações sobre como usar uma chave de API com suas chamadas para as APIs do Google Cloud, consulte Como usar chaves de API.

Antes de começar

A página usa curl com a ferramenta de linha de comando oauth2l para enviar solicitações à API de chaves de API. Consulte Primeiros passos com as chaves de API para detalhes sobre como começar a usar 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. Você só pode especificar os campos displayName e restrictions do objeto Key. O CreateKey não é um método síncrono. Em vez disso, quando você envia 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:

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

Em caso de sucesso, o método retorna uma operação de longa duração na resposta. Conforme descrito emComo pesquisar operações de longa duração, você repete repetidamenteoperations.get chamadas com o valor daname campo. Quando a resposta de operations.get contém "done": true, o objeto response contém um Key, semelhante ao seguinte:

{
  "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 para a chave de API. Você usa o valor no campo name dos outros métodos que exigem um nome de chave. Esse valor não é exibido no Console do Google Cloud, mas é possível 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 Console do Cloud. Portanto, talvez você queira 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 Console do Cloud. Você pode chamar o método GetKeyString para conseguir o keyString de uma chave de API.
  • O campo etag contém uma soma de verificação calculada pelo servidor com base no valor atual da chave. Passe o valor etag ao chamar os métodos UpdateKey e DeleteKey.

Código da chave especificada pelo usuário

Especifique um keyId como um parâmetro de consulta para o método CreateKey. Quando especificado, o valor se torna o componente final de Key.name.

Por exemplo, veja 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"

Como clonar uma chave de API

Para fazer uma cópia de uma chave de API no mesmo projeto do Cloud, use o método CloneKey. Ao chamar CloneKey, você inicia uma operação de longa duração que cria uma chave com a mesma displayName e restrictions da chave original, mas novos name e keyString.

O exemplo a seguir ilustra como chamar CloneKey:

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

Quando a resposta de operations.get contém "done": true, response contém o novo objeto Key.

A nova chave tem os mesmos displayName e restrictions que a chave original, mas um novo name e keyString.

Como atualizar o nome de exibição

Para alterar o displayName de uma chave de API ou adicionar um displayName a uma chave de API que foi criada sem uma, 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, response contém um objeto Key com a versão atualizada displayName.

Como 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, response é semelhante ao seguinte:

{
  "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 ela não é completamente removida do nosso sistema. Após 30 dias, a chave de API será excluída permanentemente. É possível adicionar um filtro ao método ListKeys para retornar chaves de API marcadas como DELETED:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

Como restaurar uma chave de API

Para restaurar uma chave de API antes de excluí-la 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