创建和管理 API 密钥

本页介绍了如何使用 API 密钥 API 创建和管理 API 密钥。

如需了解如何在对 Google Cloud API 的调用中使用 API 密钥，请参阅使用 API 密钥。

准备工作

此页面使用 curl 和 Google Cloud CLI 向 API 密钥 API 发送请求。如需详细了解如何设置 API 以进行实验，请参阅 API Keys 使用入门。

创建 API 密钥

您可以使用 CreateKey 方法创建 API 密钥。该方法需要一个 Key 参数。您只能指定 Key 对象的 displayName 和 restrictions 字段。CreateKey 不是同步方法。相反，当您向 CreateKey 发出调用时，您会启动一项长时间运行的操作。以下示例会发出 CreateKey 调用，以创建不受任何限制的 API 密钥：

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

如果成功，该方法会在响应中返回一个长时间运行的操作。如轮询长时间运行的操作中所述，您可以使用 name 字段中的值重复进行 operations.get 调用。当 operations.get 的响应包含 "done": true 时，response 对象包含 Key，如下所示：

{
  "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=="
  }
}

在 response 对象中：

  • name 字段包含 API 密钥的唯一标识符。在需要密钥名称的其他方法中，您可以使用 name 字段中的值。此值不会显示在 Google Cloud 控制台中，但您可以调用 ListKeys 方法来获取所有 API 密钥的 names。Key.name 字段始终采用以下格式：projects/PROJECT_NUMBER/locations/global/keys/KEY_ID。
  • displayName 字段会映射到Google Cloud 控制台中的 Name 字段，因此您可能需要在调用 CreateKey 时提供 displayName。
  • keyString 字段包含您发送给需要 API 密钥的 API 的字符串。keyString 对应于Google Cloud 控制台中的 API key 字段。您可以调用 GetKeyString 方法来获取 API 密钥的 keyString。
  • etag 字段包含服务器根据键的当前值计算出的校验和。调用 UpdateKey 和 DeleteKey 方法时，请传递 etag 值。

用户指定的密钥 ID

您可以将 keyId 指定为 CreateKey 方法的查询参数。如果指定了该值，则该值会成为 Key.name 的最终组成部分。

例如，请考虑以下对 CreateKey 的调用：

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

在此示例中，Key.name 字段具有以下值： 

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

更新显示名称

如需更改 API 密钥的 displayName 或向未创建 displayName 的 API 密钥添加 displayName，请调用 UpdateKey 方法。当您调用 UpdateKey 时，系统会启动一项长时间运行的操作来更新密钥。

以下示例说明了如何调用 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"}'

当 operations.get 的响应包含 "done": true 时，response 包含一个具有更新后 displayName 的 Key 对象。

删除 API 密钥

如需删除 API 密钥，请使用 DeleteKey 方法。当您调用 DeleteKey 时，系统会启动一项长时间运行的操作，将密钥标记为 DELETED。

以下示例说明了如何调用 DeleteKey：

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

如果 operations.get 的响应包含 "done": true，则 response 类似于以下内容：

{
  "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=="
  }
}

标记为 DELETED 的 API 密钥无法使用，但也不会从我们的系统中完全移除。如需列出仍存在但标记为 DELETED 的 API 密钥，请将 ListKeys 方法的 show_deleted 设置为 true：

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true

30 天后，API 密钥会被永久删除。

恢复 API 密钥

如需在 API 密钥被永久删除之前恢复该密钥，请调用 UndeleteKey 方法。当您调用 UndeleteKey 时，系统会启动一项长时间运行的操作，将密钥标记为 ACTIVE。

以下示例说明了如何调用 UndeleteKey：

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

后续步骤