创建和管理 API 密钥

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

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

准备工作

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

创建 API 密钥

您可以使用 CreateKey 方法创建 API 密钥。此方法需要 Key 参数。您只能指定 Key 对象的 displayNamerestrictions 字段。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 密钥的 namesKey.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 字段包含服务器根据键的当前值计算得出的校验和。调用 UpdateKeyDeleteKey 方法时,请传递 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 时,您会启动一个长时间运行的操作,该操作创建一个与原始密钥相同的 displayNamerestrictions,但新的 namekeyString 值。

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

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

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

新密钥与原始密钥具有相同的 displayNamerestrictions,但使用的是新的 namekeyString

更新显示名

要更改 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 包含已更新的 displayNameKey 对象。

删除 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

后续步骤