创建和管理 API 密钥

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

如需了解如何使用 API 密钥来调用 Google Cloud API，请参阅使用 API 密钥。

准备工作

该页面将 curl 与 oauth2l 命令行工具结合使用，以向 API Keys 的 API 发送请求。如需详细了解如何开始使用 API，请参阅 API 密钥使用入门。

创建 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"}'

成功后，该方法会在响应中返回一个长时间运行的操作。如轮询长时间运行的操作，您将反复调用operations.get调用带有name字段。当 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 Console 中，但您可以调用 ListKeys 方法来获取所有 API 密钥的 names。Key.name 字段始终采用以下格式：projects/PROJECT_NUMBER/locations/global/keys/KEY_ID。
displayName 字段映射到 Cloud Console 中的 Name 字段，因此在调用 CreateKey 时，您可能需要提供 displayName。
keyString 字段包含您要发送到 API 密钥的 API 的字符串。keyString 会映射到 Cloud Console 中的 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 密钥

如需在同一 Cloud 项目中复制 API 密钥，请使用 CloneKey 方法。调用 CloneKey 时，您会启动一个长时间运行的操作，该操作创建一个与原始密钥相同的 displayName 和 restrictions，但新的 name 和 keyString 值。

以下示例展示了如何调用 CloneKey：

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

当 operations.get 的响应包含 "done": true 时，response 将包含新的 Key 对象。

新密钥与原始密钥具有相同的 displayName 和 restrictions，但使用的是新的 name 和 keyString。

更新显示名

要更改 API 密钥的 displayName 或将 displayName 添加到在没有密钥的情况下创建的 API 密钥，请调用 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 密钥无法使用，但会从我们的系统中完全移除。30 天后，API 密钥将被永久删除。您可以向 ListKeys 方法添加一个过滤条件，以返回已标记为 DELETED 的 API 密钥：

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

恢复 API 密钥

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

以下示例展示了如何调用 UndeleteKey：

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