批量更新 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 密钥
resp = client.security.create_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"
]
}
},
)
print(resp)
const response = await client.security.createApiKey({
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"],
},
},
});
console.log(response);
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 密钥
resp = client.security.create_api_key(
name="my-other-api-key",
metadata={
"application": "my-application",
"environment": {
"level": 2,
"trusted": True,
"tags": [
"dev",
"staging"
]
}
},
)
print(resp)
const response = await client.security.createApiKey({
name: "my-other-api-key",
metadata: {
application: "my-application",
environment: {
level: 2,
trusted: true,
tags: ["dev", "staging"],
},
},
});
console.log(response);
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 密钥，为其分配新的角色描述符和元数据，并更新其过期时间。
resp = client.security.bulk_update_api_keys(
body={
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {
"role-a": {
"indices": [
{
"names": [
"*"
],
"privileges": [
"write"
]
}
]
}
},
"metadata": {
"environment": {
"level": 2,
"trusted": True,
"tags": [
"production"
]
}
},
"expiration": "30d"
},
)
print(resp)
const response = await client.security.bulkUpdateApiKeys({
body: {
ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
role_descriptors: {
"role-a": {
indices: [
{
names: ["*"],
privileges: ["write"],
},
],
},
},
metadata: {
environment: {
level: 2,
trusted: true,
tags: ["production"],
},
},
expiration: "30d",
},
});
console.log(response);
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 密钥先前分配的权限，使其继承拥有者用户的全部权限。
resp = client.security.bulk_update_api_keys(
body={
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
],
"role_descriptors": {}
},
)
print(resp)
const response = await client.security.bulkUpdateApiKeys({
body: {
ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
role_descriptors: {},
},
});
console.log(response);
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 密钥关联的用户权限的快照。
resp = client.security.bulk_update_api_keys(
body={
"ids": [
"VuaCfGcBCdbkQm-e5aOx",
"H3_AhoIBA9hmeQJdg7ij"
]
},
)
print(resp)
const response = await client.security.bulkUpdateApiKeys({
body: {
ids: ["VuaCfGcBCdbkQm-e5aOx", "H3_AhoIBA9hmeQJdg7ij"],
},
});
console.log(response);
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]"
}
}
}
}
}