创建和管理 API 密钥

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

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

创建 API 密钥

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys'

成功后，该方法会在响应中返回一项长时间运行的操作。如 轮询 长时间运行的操作中所述，您 可以使用 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 字段会映射到控制台中的 Name 字段，因此您可能需要在调用 CreateKey 时提供 displayName。Google Cloud
  • keyString 字段包含您发送给需要 API 密钥的 API 的字符串。keyString 会映射到 API key 字段在 Google Cloud 控制台。您可以调用 GetKeyString 方法来获取 API 密钥的 keyString。
  • etag 字段包含服务器根据密钥的当前值计算出的校验和。请在调用 UpdateKey 和 DeleteKey 方法时传递 etag 值。

用户指定的密钥 ID

您可以为 CreateKey 方法指定 keyId 作为查询参数。指定后，该值将成为 Key.name 的最后一个组成部分。

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName" : "Example API key with user-specified ID"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1'

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

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

更新显示名称

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

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
          "displayName": "New display name",
          "etag" : "ETAG"
        }' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName'

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

删除 API 密钥

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

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H 'If-Match: "ETAG"' \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID'

当 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：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true'

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

恢复 API 密钥

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

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     'https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete'

后续步骤