本页面介绍了如何使用 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