« 更新安全索引设置 SAML 准备身份验证 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›安全 API

批量更新 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 密钥永不过期。可以省略以保持不变。

响应正文

编辑

成功的请求会返回一个 JSON 结构，其中包含所有更新的 API 密钥的 ID、已具有请求的更改且不需要更新的 API 密钥的 ID，以及任何失败更新的错误详细信息。

示例

编辑

在下面的示例中，假设用户创建了两个 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]"
         }
       }
    }
  }
}

当 count 为 0 时，此字段不会出现在响应中。

发生错误的 API 密钥的 ID。

错误详细信息还可能包含 caused_by 字段。
« 更新安全索引设置 SAML 准备身份验证 API »