批量更新 API 密钥 API
编辑批量更新 API 密钥 API编辑
请求编辑
POST /_security/api_key/_bulk_update
先决条件编辑
- 要使用此 API，您必须至少具有
manage_own_api_key集群权限。用户只能更新他们创建或授予他们的 API 密钥。要更新另一个用户的 API 密钥，请使用run_as功能 代表另一个用户提交请求。
无法使用 API 密钥作为此 API 的身份验证凭据。要更新 API 密钥，需要所有者用户的凭据。
描述编辑
此 API 类似于 更新单个 API 密钥，但允许您在一个 API 调用中对多个 API 密钥应用相同的更新。与进行单独更新相比，此操作可以大大提高性能。
无法更新已过期或 已失效 的 API 密钥。
此 API 支持更新 API 密钥访问范围、元数据和到期时间。每个 API 密钥的访问范围来自您在请求中指定的 role_descriptors，以及请求时所有者用户权限的快照。所有者权限的快照会在每次调用时自动更新。
如果您未在请求中指定 role_descriptors，则调用此 API 仍然可能会更改 API 密钥的访问范围。如果所有者用户的权限自创建或上次修改 API 密钥以来已更改，则可能会发生此更改。
请求正文编辑
您可以在请求正文中指定以下参数。
-
ids - （必填，列表）要更新的 API 密钥的 ID。
-
role_descriptors - （可选，对象）要分配给 API 密钥的角色描述符。API 密钥的有效权限是其分配的权限与所有者用户权限的时间点快照的交集。您可以通过在此参数中指定新权限来分配新权限。要删除分配的权限，请将
role_descriptors参数提供为空对象{}。如果 API 密钥没有分配的权限，则它将继承所有者用户的完整权限。无论您是否提供role_descriptors参数，所有者权限的快照始终都会更新。角色描述符的结构与 创建 API 密钥 API 的请求相同。 -
metadata - （可选，对象）要与 API 密钥关联的任意嵌套元数据。
在 metadata 对象中，以下划线 (_) 开头的顶级键保留供系统使用。使用此参数指定的任何信息将完全替换以前与 API 密钥关联的元数据。
-
expiration - （可选，字符串）API 密钥的到期时间。默认情况下，API 密钥永不过期。可以省略以保持不变。
示例编辑
对于以下示例，假设用户创建了两个 API 密钥。用户创建第一个 API 密钥
POST /_security/api_key
{
"name": "my-api-key",
"role_descriptors": {
"role-a": {
"cluster": ["all"],
"indices": [
{
"names": ["index-a*"],
"privileges": ["read"]
}
]
}
},
"metadata": {
"application": "my-application",
"environment": {
"level": 1,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
这将返回包含以下 API 密钥信息的响应。
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
用户创建第二个 API 密钥
POST /_security/api_key
{
"name": "my-other-api-key",
"metadata": {
"application": "my-application",
"environment": {
"level": 2,
"trusted": true,
"tags": ["dev", "staging"]
}
}
}
导致以下 API 密钥信息。
{
"id": "H3_AhoIBA9hmeQJdg7ij",
"name": "my-other-api-key",
"api_key": "134G4ilmT_uGWXHRfJfXXA",
"encoded": "SDNfQWhvSUJBOWhtZVFKZGc3aWo6MTM0RzRpbG1UX3VHV1hIUmZKZlhYQQ=="
}
此外，假设所有者用户的权限为
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
以下示例更新了上面创建的 API 密钥，为它们分配了新的角色描述符、元数据并更新了它们的到期时间。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {
"role-a": {
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
},
"metadata": {
"environment": {
"level": 2,
"trusted": true,
"tags": ["production"]
}
},
"expiration": "30d"
}
成功的调用将返回一个 JSON 结构，指示 API 密钥已更新
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
更新后，两个 API 密钥的有效权限都将是提供的角色描述符与 所有者用户权限 的交集
{
"indices": [
{
"names": ["*"],
"privileges": ["write"]
}
]
}
以下示例删除了 API 密钥先前分配的权限，使其继承所有者用户的完整权限。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {}
}
这将返回响应
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
更新后，API 密钥的有效权限将与所有者用户的权限相同
{
"cluster": ["all"],
"indices": [
{
"names": ["*"],
"privileges": ["all"]
}
]
}
对于下一个示例，假设所有者用户的权限已从 原始权限 更改为
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
以下请求自动更新与两个 API 密钥关联的用户权限快照。
POST /_security/api_key/_bulk_update
{
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
]
}
这将返回响应
{
"updated": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"noops": []
}
导致两个 API 密钥的以下有效权限
{
"cluster": ["manage_security"],
"indices": [
{
"names": ["*"],
"privileges": ["read"]
}
]
}
如果任何 API 密钥更新失败，则错误详细信息将包含在 errors 字段中。例如
{
"updated": ["VuaCfGcBCdbkQm-e5aOx"],
"noops": [],
"errors": {
"count": 3,
"details": {
"g_PqP4IBcBaEQdwM5-WI": {
"type": "resource_not_found_exception",
"reason": "no API key owned by requesting user found for ID [g_PqP4IBcBaEQdwM5-WI]"
},
"OM4cg4IBGgpHBfLerY4B": {
"type": "illegal_argument_exception",
"reason": "cannot update invalidated API key [OM4cg4IBGgpHBfLerY4B]"
},
"Os4gg4IBGgpHBfLe2I7j": {
"type": "exception",
"reason": "bulk request execution failure",
"caused_by": {
"type" : "version_conflict_engine_exception",
"reason" : "[1]: version conflict, required seqNo [1], primary term [1]. current document has seqNo [2] and primary term [1]"
}
}
}
}
}