安全
- class elasticsearch.client.SecurityClient
To use this client, access
client.securityfrom anElasticsearchclient. For example:from elasticsearch import Elasticsearch # Create the client instance client = Elasticsearch(...) # Use the security client client.security.<method>(...)
- activate_user_profile(*, grant_type=None, access_token=None, error_trace=None, filter_path=None, human=None, password=None, pretty=None, username=None, body=None)
激活用户配置文件。
代表其他用户创建或更新用户配置文件。
注意：用户配置文件功能专为 Kibana 及 Elastic 的可观测性、企业搜索和 Elastic 安全解决方案设计。 个人用户和外部应用程序不应直接调用此 API。 调用应用程序必须拥有目标用户的
access_token或username与password组合。 Elastic 保留在未来版本中更改或移除此功能的权利，恕不另行通知。此 API 为终端用户创建或更新配置文件文档，包含从用户认证对象中提取的信息，如
username、full_name、roles及认证域。 例如，在 JWTaccess_token场景下，配置文件用户的username从 JWT 令牌声明中提取，该声明由认证令牌的 JWT 域的claims.principal设置指定。更新配置文件文档时，若文档被禁用，API 会将其启用。 任何更新都不会改变
labels或data字段的现有内容。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-activate-user-profile
- Parameters:
grant_type (str | Literal['access_token', 'password'] | None) – 授权类型。
access_token (str | None) – 用户的 Elasticsearch 访问令牌或 JWT。支持 access 和 id 两种 JWT 令牌类型，具体取决于底层 JWT 域配置。若指定 access_token 授权类型，此参数必填且不适用于其他授权类型。
password (str | None) – 用户密码。若指定 password 授权类型，此参数必填且不适用于其他授权类型。
username (str | None) – 标识用户的用户名。若指定 password 授权类型，此参数必填且不适用于其他授权类型。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- authenticate(*, error_trace=None, filter_path=None, human=None, pretty=None)
用户认证。
认证用户并返回认证用户的信息。 需在基础认证头中包含用户信息。 成功调用返回 JSON 结构，显示用户名、分配的角色、元数据及认证授权该用户的域信息。 若认证失败，此 API 返回 401 状态码。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-authenticate
- bulk_delete_role(*, names=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None, body=None)
批量删除角色。
角色管理 API 通常是管理角色的首选方式，而非基于文件的角色管理。 批量删除角色 API 无法删除角色文件中定义的角色。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-bulk-delete-role
- bulk_put_role(*, roles=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None, body=None)
批量创建或更新角色。
角色管理 API 通常是管理角色的首选方式，而非基于文件的角色管理。 批量创建或更新角色 API 无法更新角色文件中定义的角色。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-bulk-put-role
- Parameters:
- Return type:
- bulk_update_api_keys(*, ids=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, role_descriptors=None, body=None)
批量更新 API 密钥。 修改多个 API 密钥的属性。
重要：无法使用 API 密钥作为此 API 的认证凭证。更新 API 密钥需要提供所有者用户的凭据。
此 API 与更新 API 密钥 API 类似，但允许在单次 API 调用中对多个 API 密钥应用相同更新。此操作相比单独更新可显著提升性能。
无法更新已过期或失效的 API 密钥。
此 API 支持更新 API 密钥的访问范围、元数据和过期时间。 每个 API 密钥的访问范围由请求中指定的
role_descriptors及请求时所有者用户权限的快照决定。 所有者权限的快照会在每次调用时自动更新。重要：若请求中未指定
role_descriptors，调用此 API 仍可能改变 API 密钥的访问范围。若所有者用户权限自 API 密钥创建或上次修改后发生变化，则可能发生此变更。成功请求返回 JSON 结构，包含所有已更新 API 密钥的 ID、已具备请求变更无需更新的 API 密钥 ID，以及任何失败更新的错误详情。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-bulk-update-api-keys
- Parameters:
expiration (str | Literal[-1] | ~typing.Literal[0] | None) – API 密钥的过期时间。默认情况下 API 密钥永不过期。可省略此属性以保持原值不变。
metadata (Mapping[str, Any] | None) – 与 API 密钥关联的任意嵌套元数据。在 metadata 对象中，以下划线 (_) 开头的顶级键保留给系统使用。此参数指定的信息将完全替换之前与 API 密钥关联的元数据。
role_descriptors (Mapping[str, Mapping[str, Any]] | None) – 分配给 API 密钥的角色描述符。API 密钥的有效权限是其分配权限与所有者用户实时权限快照的交集。可通过此参数指定新权限。要移除已分配权限，需将 role_descriptors 参数设为空对象 {}。若 API 密钥无分配权限，则继承所有者用户的完整权限。无论是否提供 role_descriptors 参数，所有者权限的快照始终会更新。角色描述符的结构与创建 API 密钥 API 的请求相同。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- change_password(*, username=None, error_trace=None, filter_path=None, human=None, password=None, password_hash=None, pretty=None, refresh=None, body=None)
修改密码。
更改原生域用户和内置用户的密码。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-change-password
- Parameters:
username (str | None) – 需要修改密码的用户名。如果不指定此参数，则修改当前用户的密码。
password (str | None) – 新密码值。密码长度必须至少为6个字符。
password_hash (str | None) – 新密码的哈希值。必须使用与密码存储配置相同的哈希算法生成。 更多细节请参阅 xpack.security.authc.password_hashing.algorithm 设置的说明。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为 true`（默认值），则刷新受影响的分片使操作对搜索可见； 如果为 `wait_for，则等待刷新使操作对搜索可见； 如果为 false，则不进行任何刷新操作。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- clear_api_key_cache(*, ids, error_trace=None, filter_path=None, human=None, pretty=None)
清除API密钥缓存。
从API密钥缓存中驱逐部分条目。 当安全索引状态发生变化时，缓存也会自动清除。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-clear-api-key-cache
- clear_cached_privileges(*, application, error_trace=None, filter_path=None, human=None, pretty=None)
清除权限缓存。
从原生应用程序权限缓存中驱逐权限。 当应用程序权限更新时，其缓存也会自动清除。
- clear_cached_realms(*, realms, error_trace=None, filter_path=None, human=None, pretty=None, usernames=None)
清除用户缓存。
从用户缓存中驱逐用户。 可以完全清除缓存或驱逐特定用户。
用户凭证缓存在每个节点的内存中，以避免每次请求都连接远程认证服务或访问磁盘。 可以通过领域设置来配置用户缓存。 更多信息请参阅关于控制用户缓存的文档。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-clear-cached-realms
- Parameters:
- Return type:
- clear_cached_roles(*, name, error_trace=None, filter_path=None, human=None, pretty=None)
清除角色缓存。
从原生角色缓存中驱逐角色。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-clear-cached-roles
- clear_cached_service_tokens(*, namespace, service, name, error_trace=None, filter_path=None, human=None, pretty=None)
清除服务账户令牌缓存。
从服务账户令牌缓存中驱逐部分条目。 服务账户令牌存在两个独立的缓存：一个缓存用于由
service_tokens文件支持的令牌，另一个用于由.security索引支持的令牌。 此API会同时清除两个缓存中的匹配条目。由
.security索引支持的令牌缓存会在安全索引状态变更时自动清除。 由service_tokens文件支持的令牌缓存会在文件变更时自动清除。- Parameters:
- Return type:
- create_api_key(*, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, name=None, pretty=None, refresh=None, role_descriptors=None, body=None)
创建API密钥。
创建一个无需基本认证即可访问的API密钥。
重要提示：如果用于认证此请求的凭证是API密钥，则派生的API密钥不能拥有任何权限。 如果指定了权限，API将返回错误。
成功请求会返回一个包含API密钥、其唯一ID和名称的JSON结构。 如果适用，还会以毫秒为单位返回API密钥的过期信息。
注意：默认情况下，API密钥永不过期。创建API密钥时可指定过期信息。
API密钥由Elasticsearch API密钥服务创建，该服务默认启用。 要配置或关闭API密钥服务，请参阅API密钥服务设置文档。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key
- Parameters:
expiration (str | Literal[-1] | ~typing.Literal[0] | None) – API密钥的过期时间。默认情况下API密钥永不过期。
metadata (Mapping[str, Any] | None) – 要与API密钥关联的任意元数据。 支持嵌套数据结构。在元数据对象中，以`_`开头的键保留给系统使用。
name (str | None) – API密钥的名称。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为`true`（默认值）则刷新受影响分片使操作对搜索可见； 如果为`wait_for`则等待刷新使操作对搜索可见； 如果为`false`则不进行任何刷新操作。
role_descriptors (Mapping[str, Mapping[str, Any]] | None) – 此API密钥的角色描述符数组。 当未指定或为空数组时，API密钥将拥有认证用户权限的时间点快照。 如果提供角色描述符，最终权限将是API密钥权限与认证用户权限的交集， 从而限制API密钥的访问范围。角色描述符的结构与创建角色API的请求相同。 注意：由于权限交集的计算方式，除非派生密钥创建时不带任何权限， 否则无法创建作为另一个API密钥子级的API密钥。 派生API密钥可用于认证，但无权调用Elasticsearch API。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- create_cross_cluster_api_key(*, access=None, name=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, body=None)
创建跨集群API密钥。
为基于API密钥的远程集群访问创建
cross_cluster类型的API密钥。cross_clusterAPI密钥不能用于通过REST接口进行认证。重要提示：要认证此请求，必须使用非API密钥的凭证。即使使用具有所需权限的API密钥，API也会返回错误。
跨集群API密钥由默认启用的Elasticsearch API密钥服务创建。
注意：与REST API密钥不同，跨集群API密钥不会捕获认证用户的权限。 API密钥的有效权限完全由
access属性指定。成功请求会返回包含API密钥、其唯一ID和名称的JSON结构。 如果适用，还会以毫秒为单位返回过期信息。
默认情况下API密钥永不过期。创建时可指定过期信息。
跨集群API密钥只能通过更新跨集群API密钥API进行更新。 尝试使用更新REST API密钥API或批量更新REST API密钥API更新会导致错误。
- Parameters:
access (Mapping[str, Any] | None) – 授予此API密钥的访问权限。 该访问权限由跨集群搜索和跨集群复制的权限组成。 至少必须指定其中一项。注意：不应为搜索或复制访问指定显式权限。 创建过程会自动将访问规范转换为具有相应权限的角色描述符。
name (str | None) – 指定此API密钥的名称。
expiration (str | Literal[-1] | ~typing.Literal[0] | None) – API密钥的过期时间。默认永不过期。
metadata (Mapping[str, Any] | None) – 要与API密钥关联的任意元数据。 支持嵌套数据结构。元数据对象中以`_`开头的键保留给系统使用。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- create_service_token(*, namespace, service, name=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
创建服务账户令牌。
创建一个无需基本认证即可访问的服务账户令牌。
注意：服务账户令牌永不过期。 如果不再需要，必须主动删除它们。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token
- Parameters:
namespace (str) – 命名空间名称，即服务账户的顶级分组。
service (str) – 服务名称。
name (str | None) – 服务账户令牌的名称。如果省略，将生成随机名称。 令牌名称长度必须在1到256个字符之间，可包含字母数字字符(a-z, A-Z, 0-9)、 短划线(-)和下划线(_)，但不能以下划线开头。 注意：令牌名称在关联服务账户上下文中必须唯一。 其完全限定名称(格式为`<命名空间>/<服务>/<令牌名称>`)也必须在全局范围内唯一。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为`true`则刷新受影响分片使操作对搜索可见； 如果为`wait_for`（默认值）则等待刷新使操作对搜索可见； 如果为`false`则不进行任何刷新操作。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- delegate_pki(*, x509_certificate_chain=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)
委托PKI认证。
此API实现将X509证书链交换为Elasticsearch访问令牌的功能。 证书链根据RFC 5280，通过依次考虑每个已安装PKI域的信任配置进行验证， 这些域的
delegation.enabled设置为true。 成功受信任的客户端证书还需根据相应域的username_pattern验证主题专有名称。此API由智能且可信的代理（如Kibana）调用，这些代理终止用户的TLS会话， 但仍希望通过PKI域对用户进行认证——就像用户直接连接到Elasticsearch一样。
重要提示：目标证书中的主题公钥与对应私钥之间的关联性不会被验证。 这是TLS认证过程的一部分，已委托给调用此API的代理。 代理被信任已执行TLS认证，此API将该认证转换为Elasticsearch访问令牌。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delegate-pki
- delete_privileges(*, application, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
删除应用程序权限。
使用此API需要具备以下任一权限：
- 集群权限
manage_security（或更高权限如all）。 - 请求中引用的应用程序的"管理应用程序权限"全局权限。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-privileges
- 集群权限
- delete_role(*, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
删除角色。
删除原生领域的角色。 角色管理API通常是管理角色的首选方式，而非使用基于文件的角色管理。 删除角色API无法移除角色文件中定义的角色。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-role
- Parameters:
- Return type:
- delete_role_mapping(*, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
删除角色映射。
角色映射定义了分配给每个用户的角色。 角色映射API通常是管理角色映射的首选方式，而非使用角色映射文件。 删除角色映射API无法移除角色映射文件中定义的映射。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-role-mapping
- delete_service_token(*, namespace, service, name, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
删除服务账户令牌。
删除指定命名空间中服务的服务账户令牌。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-service-token
- Parameters:
- Return type:
- delete_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
删除用户。
从原生领域删除用户。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-delete-user
- Parameters:
- Return type:
- disable_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
禁用用户。
在原生域中禁用用户。 默认情况下，创建用户时他们处于启用状态。 您可以使用此API撤销用户对Elasticsearch的访问权限。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-disable-user
- Parameters:
- Return type:
- disable_user_profile(*, uid, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
禁用用户配置文件。
禁用用户配置文件，使其在用户配置文件搜索中不可见。
注意：用户配置文件功能专为Kibana及Elastic的可观测性、企业搜索和Elastic安全解决方案设计。 个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或移除该功能的权利，恕不另行通知。
当您激活用户配置文件时，它会自动启用并在用户配置文件搜索中可见。您可以使用禁用用户配置文件API来禁用用户配置文件，使其在这些搜索中不可见。 要重新启用已禁用的用户配置文件，请使用启用用户配置文件API。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-disable-user-profile
- enable_user(*, username, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
启用用户。
在原生域中启用用户。 默认情况下，创建用户时他们处于启用状态。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-enable-user
- Parameters:
- Return type:
- enable_user_profile(*, uid, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
启用用户配置文件。
启用用户配置文件，使其在用户配置文件搜索中可见。
注意：用户配置文件功能专为Kibana及Elastic的可观测性、企业搜索和Elastic安全解决方案设计。 个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或移除该功能的权利，恕不另行通知。
当您激活用户配置文件时，它会自动启用并在用户配置文件搜索中可见。 如果您之后禁用了用户配置文件，可以使用启用用户配置文件API使该配置文件再次在这些搜索中可见。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-enable-user-profile
- enroll_kibana(*, error_trace=None, filter_path=None, human=None, pretty=None)
注册Kibana。
使Kibana实例能够配置自身以与安全的Elasticsearch集群通信。
注意：此API目前仅供Kibana内部使用。 Kibana内部使用此API来配置自身与已启用安全功能的Elasticsearch集群的通信。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-enroll-kibana
- enroll_node(*, error_trace=None, filter_path=None, human=None, pretty=None)
注册节点。
注册一个新节点，使其能够加入已启用安全功能的现有集群。
响应包含加入节点所需的所有信息，用于引导发现和安全相关设置，使其能够成功加入集群。 响应包含密钥和证书材料，允许调用者为集群中所有节点的HTTP层生成有效的签名证书。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-enroll-node
- get_api_key(*, active_only=None, error_trace=None, filter_path=None, human=None, id=None, name=None, owner=None, pretty=None, realm_name=None, username=None, with_limited_by=None, with_profile_uid=None)
获取API密钥信息。
检索一个或多个API密钥的信息。 注意：如果仅拥有
manage_own_api_key权限，此API仅返回您拥有的API密钥。 如果拥有read_security、manage_api_key或更高权限（包括manage_security），此API将返回所有API密钥，无论所有权归属。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-api-key
- Parameters:
active_only (bool | None) – 布尔标志，用于查询当前活跃的API密钥。如果API密钥在查询时既未失效也未过期，则视为活跃。可与其他参数如`owner`或`name`一起使用。如果`active_only`为false，响应将包含活跃和非活跃（过期或失效）的密钥。
id (str | None) – API密钥ID。此参数不能与`name`、`realm_name`或`username`同时使用。
name (str | None) – API密钥名称。此参数不能与`id`、`realm_name`或`username`同时使用。支持通配符前缀搜索。
owner (bool | None) – 布尔标志，用于查询当前认证用户拥有的API密钥。当此参数设为`true`时，不能指定`realm_name`或`username`参数，因为它们被假定为当前认证用户。
realm_name (str | None) – 认证域名称。此参数不能与`id`或`name`同时使用，也不能在`owner`标志设为`true`时使用。
username (str | None) – 用户名。此参数不能与`id`或`name`同时使用，也不能在`owner`标志设为`true`时使用。
with_limited_by (bool | None) – 返回与API密钥关联的所有者用户角色描述符的快照。API密钥的实际权限是其分配的角色描述符与所有者用户角色描述符的交集。
with_profile_uid (bool | None) – 确定是否同时检索API密钥所有者主体的profile uid（如果存在）。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- get_builtin_privileges(*, error_trace=None, filter_path=None, human=None, pretty=None)
获取内置权限。
获取当前Elasticsearch版本可用的集群权限和索引权限列表。
- get_privileges(*, application=None, name=None, error_trace=None, filter_path=None, human=None, pretty=None)
获取应用程序权限。
使用此API需要具备以下任一权限：
read_security集群权限（或更高权限如manage_security或all）。- 请求中引用的应用程序的"管理应用程序权限"全局权限。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-privileges
- Parameters:
- Return type:
- get_role(*, name=None, error_trace=None, filter_path=None, human=None, pretty=None)
获取角色。
获取原生域中的角色。 角色管理API通常是管理角色的首选方式，而非基于文件的角色管理。 获取角色API无法检索在角色文件中定义的角色。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-role
- get_role_mapping(*, name=None, error_trace=None, filter_path=None, human=None, pretty=None)
获取角色映射。
角色映射定义了每个用户被分配的角色。 通常推荐使用角色映射API来管理角色映射，而非使用角色映射文件。 获取角色映射API无法检索通过角色映射文件定义的映射。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-role-mapping
- get_service_accounts(*, namespace=None, service=None, error_trace=None, filter_path=None, human=None, pretty=None)
获取服务账户。
获取符合路径参数的服务账户列表。
注意：当前仅支持
elastic/fleet-server服务账户。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-service-accounts
- get_service_credentials(*, namespace, service, error_trace=None, filter_path=None, human=None, pretty=None)
获取服务账户凭证。
使用此API需要至少具备
read_security集群权限（或更高权限如manage_service_account或manage_security）。响应包含通过创建服务账户令牌API生成的令牌，以及来自集群所有节点的文件型令牌。
注意：对于
service_tokens文件支持的令牌，API会从集群所有节点收集。 不同节点上同名的令牌会被视为同一令牌，在统计服务令牌总数时仅计算一次。
- get_settings(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)
获取安全索引设置。
获取安全内部索引（
.security及相关索引）的用户可配置设置。 仅显示用户可配置的索引设置子集，包括：index.auto_expand_replicasindex.number_of_replicas
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-settings
- get_token(*, error_trace=None, filter_path=None, grant_type=None, human=None, kerberos_ticket=None, password=None, pretty=None, refresh_token=None, scope=None, username=None, body=None)
获取令牌。
创建无需基础认证的承载令牌。 令牌由Elasticsearch令牌服务生成，该服务在HTTP接口配置TLS时自动启用。 也可通过显式启用
xpack.security.authc.token.enabled设置。 生产模式下，除非同时在HTTP接口启用TLS，否则引导检查会阻止启用令牌服务。获取令牌API采用与标准OAuth 2.0令牌API相同的参数（除使用JSON请求体外）。
成功调用返回包含访问令牌、过期时间（秒）、类型及可用范围的JSON结构。
获取的令牌具有有限有效期，过期后不可用。 有效期由
xpack.security.authc.token.timeout设置定义。 如需立即失效令牌，可使用撤销令牌API。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-token
- Parameters:
grant_type (str | Literal['_kerberos', 'client_credentials', 'password', 'refresh_token'] | None) – 授权类型。支持类型：password、 _kerberos、client_credentials 和 refresh_token。
kerberos_ticket (str | None) – Base64编码的Kerberos票据。若指定 _kerberos 类型， 此参数必填。其他类型无效。
password (str | None) – 用户密码。若指定 password 类型，此参数必填。 其他类型无效。
refresh_token (str | None) – 创建令牌时返回的字符串，用于延长生命周期。 若指定 refresh_token 类型，此参数必填。其他类型无效。
scope (str | None) – 令牌范围。当前无论请求值为何，仅颁发FULL范围的令牌。
username (str | None) – 标识用户的用户名。若指定 password 类型， 此参数必填。其他类型无效。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- get_user(*, username=None, error_trace=None, filter_path=None, human=None, pretty=None, with_profile_uid=None)
获取用户信息。
获取原生领域和内置用户的相关信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-user
- Parameters:
- Return type:
- get_user_privileges(*, error_trace=None, filter_path=None, human=None, pretty=None)
获取用户权限。
获取当前登录用户的安全权限。 所有用户都可以使用此API，但只能用于确定自己的权限。 要检查其他用户的权限，必须使用run as功能。 要检查用户是否具有特定权限列表，请使用has privileges API。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-user-privileges
- get_user_profile(*, uid, data=None, error_trace=None, filter_path=None, human=None, pretty=None)
获取用户配置文件。
使用唯一的配置文件ID获取用户的配置文件。
注意：用户配置文件功能专为Kibana和Elastic的可观测性、企业搜索及安全解决方案设计。 个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或删除此功能的权利，恕不另行通知。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-get-user-profile
- Parameters:
- Return type:
- grant_api_key(*, api_key=None, grant_type=None, access_token=None, error_trace=None, filter_path=None, human=None, password=None, pretty=None, refresh=None, run_as=None, username=None, body=None)
授予API密钥。
代表其他用户创建API密钥。 此API与创建API密钥API类似，但它为不同于运行API的用户创建API密钥。 调用者必须具有代表其创建API密钥的用户的认证凭据。 没有该用户的凭据，无法使用此API创建API密钥。 支持的用户认证凭据类型包括：
- 用户名和密码
- Elasticsearch访问令牌
- JWT
提供认证凭据的用户可以选择“run as”（模拟）另一个用户。 在这种情况下，API密钥将代表被模拟的用户创建。
此API旨在供需要为终端用户创建和管理API密钥，但无法保证这些用户有权代表自己创建API密钥的应用程序使用。 API密钥由自动启用的Elasticsearch API密钥服务创建。
成功的grant API key API调用返回一个包含API密钥、其唯一ID和名称的JSON结构。 如果适用，它还以毫秒为单位返回API密钥的过期信息。
默认情况下，API密钥永不过期。您可以在创建API密钥时指定过期信息。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-grant-api-key
- Parameters:
grant_type (str | Literal['access_token', 'password'] | None) – 授权类型。支持的授权类型包括：access_token、password。
access_token (str | None) – 用户的访问令牌。如果指定`access_token`授权类型，则此参数为必需。 它不适用于其他授权类型。
password (str | None) – 用户的密码。如果指定`password`授权类型，则此参数为必需。 它不适用于其他授权类型。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为’true’，Elasticsearch刷新受影响的分片以使此操作对搜索可见。 如果为’wait_for’，则等待刷新以使此操作对搜索可见。 如果为’false’，则不进行任何刷新操作。
run_as (str | None) – 要模拟的用户名。
username (str | None) – 标识用户的用户名。如果指定`password`授权类型，则此参数为必需。 它不适用于其他授权类型。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- has_privileges(*, user=None, application=None, cluster=None, error_trace=None, filter_path=None, human=None, index=None, pretty=None, body=None)
检查用户权限。
确定指定用户是否具有指定的权限列表。 所有用户都可以使用此API，但只能用于确定自己的权限。 要检查其他用户的权限，必须使用run as功能。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-has-privileges
- Parameters:
user (str | None) – 用户名
cluster (Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_esql', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_esql', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None) – 要检查的集群权限列表。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- has_privileges_user_profile(*, privileges=None, uids=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)
检查用户配置文件权限。
确定与指定用户配置文件ID关联的用户是否拥有所有请求的权限。
注意：用户配置文件功能专为Kibana及Elastic的可观测性、企业搜索和Elastic安全解决方案设计。个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或移除该功能的权利，恕不另行通知。
- invalidate_api_key(*, error_trace=None, filter_path=None, human=None, id=None, ids=None, name=None, owner=None, pretty=None, realm_name=None, username=None, body=None)
使API密钥失效。
此API将使通过创建API密钥或授予API密钥API创建的密钥失效。 失效的API密钥将无法通过认证，但在配置的保留期内仍可通过获取API密钥信息和查询API密钥信息API查看，直到被自动删除。
使用此API需至少拥有
manage_security、manage_api_key或manage_own_api_key集群权限。manage_security权限允许删除任何API密钥，包括REST和跨集群API密钥。manage_api_key权限允许删除任何REST API密钥，但不包括跨集群API密钥。manage_own_api_key仅允许删除用户自有的REST API密钥。 此外，使用manage_own_api_key权限时，失效请求必须符合以下三种格式之一：- 设置参数
owner=true。 - 或同时设置
username和realm_name以匹配用户身份。 - 或如果请求由API密钥发起（即API密钥使自身失效），需在
ids字段指定其ID。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-invalidate-api-key
- Parameters:
id (str | None)
ids (Sequence[str] | None) – API密钥ID列表。此参数不能与`name`、`realm_name`或`username`同时使用。
name (str | None) – API密钥名称。此参数不能与`ids`、`realm_name`或`username`同时使用。
owner (bool | None) – 查询当前认证用户拥有的API密钥。当此参数设为`true`时，不能指定`realm_name`或`username`参数，因为它们默认为当前认证用户。注意： 如果`owner`为`false`，则必须指定`ids`、name、`username`和`realm_name`中的至少一个。
realm_name (str | None) – 认证域名称。此参数不能与`ids`或`name`同时使用，或在`owner`标志设为`true`时使用。
username (str | None) – 用户名。此参数不能与`ids`或`name`同时使用，或在`owner`标志设为`true`时使用。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- 设置参数
- invalidate_token(*, error_trace=None, filter_path=None, human=None, pretty=None, realm_name=None, refresh_token=None, token=None, username=None, body=None)
使令牌失效。
通过获取令牌API返回的访问令牌具有有限的有效期。超过该期限后，它们将无法继续使用。 该期限由
xpack.security.authc.token.timeout设置定义。通过获取令牌API返回的刷新令牌仅24小时内有效，且只能使用一次。 如需立即使一个或多个访问或刷新令牌失效，请使用此失效令牌API。
注意：虽然所有参数均为可选，但至少需要指定其中一个。 更具体地说，必须指定`token`或`refresh_token`参数之一。 如果这两个参数均未指定，则需要指定`realm_name`和/或`username`。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-invalidate-token
- Parameters:
realm_name (str | None) – 认证域名称。此参数不能与`refresh_token`或`token`同时使用。
refresh_token (str | None) – 刷新令牌。如果使用了`refresh_token`、`realm_name`或`username`中的任何一个，则不能使用此参数。
token (str | None) – 访问令牌。如果使用了`refresh_token`、`realm_name`或`username`中的任何一个，则不能使用此参数。
username (str | None) – 用户名。此参数不能与`refresh_token`或`token`同时使用。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- oidc_authenticate(*, nonce=None, redirect_uri=None, state=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)
OpenID Connect认证。
将OpenID Connect认证响应消息交换为Elasticsearch内部访问令牌和刷新令牌，后续可用于认证。
Elasticsearch通过OpenID Connect API公开所有必要的OpenID Connect相关功能。 这些API被Kibana内部用于提供基于OpenID Connect的认证，但也可被其他自定义Web应用程序或客户端使用。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-oidc-authenticate
- Parameters:
nonce (str | None) – 将客户端会话与ID令牌关联并减轻重放攻击。此值需与提供给`/_security/oidc/prepare` API的值相同，或与Elasticsearch生成并包含在该调用响应中的值相同。
redirect_uri (str | None) – OpenID Connect提供者在成功认证后重定向用户代理的URL。此URL必须按原样提供（URL编码），取自响应体或OpenID Connect提供者响应中的location头值。
state (str | None) – 在认证请求和响应之间保持状态。此值需与提供给`/_security/oidc/prepare` API的值相同，或与Elasticsearch生成并包含在该调用响应中的值相同。
realm (str | None) – OpenID Connect域名称。在定义多个域的情况下此属性很有用。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- oidc_logout(*, token=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh_token=None, body=None)
OpenID Connect登出。
使作为对
/_security/oidc/authenticateAPI响应生成的访问令牌和刷新令牌失效。如果Elasticsearch中的OpenID Connect认证域配置得当，此调用的响应将包含指向OpenID Connect提供者会话终止端点的URI，以执行单点登出。
Elasticsearch通过OpenID Connect API公开所有必要的OpenID Connect相关功能。 这些API被Kibana内部用于提供基于OpenID Connect的认证，但也可被其他自定义Web应用程序或客户端使用。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-oidc-logout
- oidc_prepare_authentication(*, error_trace=None, filter_path=None, human=None, iss=None, login_hint=None, nonce=None, pretty=None, realm=None, state=None, body=None)
准备 OpenID Connect 认证。
基于 Elasticsearch 中 OpenID Connect 认证域的配置，创建一个 oAuth 2.0 认证请求 URL 字符串。
该 API 的响应是一个指向已配置 OpenID Connect 提供者授权端点的 URL，可用于重定向用户浏览器以继续认证流程。
Elasticsearch 通过 OpenID Connect API 暴露了所有必要的 OpenID Connect 相关功能。 Kibana 内部使用这些 API 来提供基于 OpenID Connect 的认证，但其他自定义 Web 应用或客户端也可以使用。
- Parameters:
iss (str | None) – 在第三方发起单点登录的情况下，这是 RP 要发送认证请求的 OP 的颁发者标识符。 当指定 realm 时不能指定此参数。realm 或 iss 必须指定其中一个。
login_hint (str | None) – 在第三方发起单点登录的情况下，这是一个字符串值，作为 login_hint 参数包含在认证请求中。 当指定 realm 时此参数无效。
nonce (str | None) – 用于将客户端会话与 ID 令牌关联并减轻重放攻击的值。如果 API 调用者未提供值， Elasticsearch 将生成一个具有足够熵的值并在响应中返回。
realm (str | None) – Elasticsearch 中 OpenID Connect 域的名称，其配置将用于生成认证请求。 当指定 iss 时不能指定此参数。realm 或 iss 必须指定其中一个。
state (str | None) – 用于在认证请求和响应之间保持状态的值，通常用于跨站请求伪造(CSRF)防护。 如果 API 调用者未提供值，Elasticsearch 将生成一个具有足够熵的值并在响应中返回。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- put_privileges(*, privileges=None, body=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh=None)
创建或更新应用权限。
要使用此 API，您必须拥有以下权限之一：
manage_security集群权限（或更高级权限如all）。- 请求中引用的应用的"管理应用权限"全局权限。
应用名称由前缀和可选后缀组成，需符合以下规则：
- 前缀必须以小写 ASCII 字母开头。
- 前缀只能包含 ASCII 字母或数字。
- 前缀长度至少为 3 个字符。
- 如果存在后缀，必须以短横线
-或下划线_开头。 - 后缀不能包含以下字符：
\,/,*,?,",<,>,|,,,*。 - 名称的任何部分都不能包含空格。
权限名称必须以小写 ASCII 字母开头，且只能包含 ASCII 字母、数字以及字符
_,-和.。操作名称可以包含任意数量的可打印 ASCII 字符，且必须至少包含以下字符之一：
/,*,:。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-privileges
- Parameters:
- Return type:
- put_role(*, name, applications=None, cluster=None, description=None, error_trace=None, filter_path=None, global_=None, human=None, indices=None, metadata=None, pretty=None, refresh=None, remote_cluster=None, remote_indices=None, run_as=None, transient_metadata=None, body=None)
创建或更新角色。
角色管理 API 通常是管理原生域中角色的首选方式，而不是使用基于文件的角色管理。 创建或更新角色 API 无法更新在角色文件中定义的角色。 基于文件的角色管理在 Elastic Serverless 中不可用。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role
- Parameters:
name (str) – 正在创建或更新的角色名称。在 Elasticsearch Serverless 上， 角色名称必须以字母或数字开头，且只能包含字母、数字以及字符 ‘_’, ‘-’ 和 ‘.’。 每个角色必须具有唯一名称，这将作为该角色的标识符。
applications (Sequence[Mapping[str, Any]] | None) – 应用权限条目列表。
cluster (Sequence[str | Literal['all', 'cancel_task', 'create_snapshot', 'cross_cluster_replication', 'cross_cluster_search', 'delegate_pki', 'grant_api_key', 'manage', 'manage_api_key', 'manage_autoscaling', 'manage_behavioral_analytics', 'manage_ccr', 'manage_data_frame_transforms', 'manage_data_stream_global_retention', 'manage_enrich', 'manage_esql', 'manage_ilm', 'manage_index_templates', 'manage_inference', 'manage_ingest_pipelines', 'manage_logstash_pipelines', 'manage_ml', 'manage_oidc', 'manage_own_api_key', 'manage_pipeline', 'manage_rollup', 'manage_saml', 'manage_search_application', 'manage_search_query_rules', 'manage_search_synonyms', 'manage_security', 'manage_service_account', 'manage_slm', 'manage_token', 'manage_transform', 'manage_user_profile', 'manage_watcher', 'monitor', 'monitor_data_frame_transforms', 'monitor_data_stream_global_retention', 'monitor_enrich', 'monitor_esql', 'monitor_inference', 'monitor_ml', 'monitor_rollup', 'monitor_snapshot', 'monitor_stats', 'monitor_text_structure', 'monitor_transform', 'monitor_watcher', 'none', 'post_behavioral_analytics_event', 'read_ccr', 'read_fleet_secrets', 'read_ilm', 'read_pipeline', 'read_security', 'read_slm', 'transport_client', 'write_connector_secrets', 'write_fleet_secrets']] | None) – 集群权限列表。这些权限定义了具有此角色的用户的集群级操作。
description (str | None) – 角色描述符的可选描述
global – 定义全局权限的对象。全局权限是一种具有请求感知能力的集群权限形式。 目前对全局权限的支持仅限于应用权限的管理。
metadata (Mapping[str, Any] | None) – 可选元数据。在元数据对象中，以下划线(_)开头的键保留供系统使用。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为 true`（默认值），则刷新受影响的分片使此操作对搜索可见； 如果为 `wait_for，则等待刷新使此操作对搜索可见； 如果为 false，则不进行任何刷新操作。
remote_cluster (Sequence[Mapping[str, Any]] | None) – 远程集群权限条目列表。
remote_indices (Sequence[Mapping[str, Any]] | None) – 远程索引权限条目列表。注意：远程索引仅对配置了基于 API 密钥模型的远程集群有效。 对于配置了基于证书模型的远程集群无效。
run_as (Sequence[str] | None) – 此角色所有者可以模拟的用户列表。 注意：在 Serverless 中，run-as 功能被禁用。为了 API 兼容性， 您仍然可以指定一个空的 run_as 字段，但非空列表将被拒绝。
transient_metadata (Mapping[str, Any] | None) – 指示可能与当前集群许可证不兼容的角色，特别是具有文档和字段级安全性的角色。 当集群许可证不允许某个角色的某些功能时，此参数会动态更新以列出不兼容的功能。 如果 enabled 为 false，则忽略该角色，但仍会在认证 API 的响应中列出。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- put_role_mapping(*, name, enabled=None, error_trace=None, filter_path=None, human=None, metadata=None, pretty=None, refresh=None, role_templates=None, roles=None, rules=None, run_as=None, body=None)
创建或更新角色映射。
角色映射定义了哪些角色分配给每个用户。 每个映射都有识别用户的规则和授予这些用户的角色列表。 角色映射 API 通常是管理角色映射的首选方式，而不是使用角色映射文件。创建或更新角色映射 API 无法更新在角色映射文件中定义的映射。
注意：此 API 不创建角色。而是将用户映射到现有角色。 角色可以通过创建或更新角色 API 或角色文件来创建。
角色模板
角色映射最常见的用途是从用户上的已知值创建到固定角色名称的映射。 例如，
cn=admin,dc=example,dc=comLDAP 组中的所有用户都应被授予 Elasticsearch 中的超级用户角色。roles字段用于此目的。对于更复杂的需求，可以使用 Mustache 模板动态确定应授予用户的角色名称。
role_templates字段用于此目的。注意：要成功使用角色模板，必须启用相关的脚本功能。 否则，所有尝试创建带有角色模板的角色映射都会失败。
角色映射规则中可用的所有用户字段也可在角色模板中使用。 因此可以将用户分配到反映其用户名、组或认证域名称的角色。
默认情况下，模板被评估为生成单个字符串，即应分配给用户的角色名称。 如果模板格式设置为 "json"，则期望模板生成一个 JSON 字符串或角色名称的 JSON 字符串数组。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-role-mapping
- Parameters:
name (str) – 标识角色映射的唯一名称。该名称仅用作通过 API 交互的标识符； 不会以任何方式影响映射的行为。
enabled (bool | None) – 当执行角色映射时，enabled 设置为 false 的映射将被忽略。
metadata (Mapping[str, Any] | None) – 帮助定义哪些角色分配给每个用户的附加元数据。 在元数据对象中，以 _ 开头的键保留供系统使用。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 如果为 true`（默认值），则刷新受影响的分片使此操作对搜索可见； 如果为 `wait_for，则等待刷新使此操作对搜索可见； 如果为 false，则不进行任何刷新操作。
role_templates (Sequence[Mapping[str, Any]] | None) – Mustache 模板列表，将评估这些模板以确定应授予匹配角色映射规则的用户的角色名称。 必须指定 roles 或 role_templates 中的一个。
roles (Sequence[str] | None) – 角色名称列表，授予匹配角色映射规则的用户。 必须指定 roles 或 role_templates 中的一个。
rules (Mapping[str, Any] | None) – 确定哪些用户应被映射匹配的规则。 规则是使用 JSON DSL 表达的逻辑条件。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- put_user(*, username, email=None, enabled=None, error_trace=None, filter_path=None, full_name=None, human=None, metadata=None, password=None, password_hash=None, pretty=None, refresh=None, roles=None, body=None)
创建或更新用户。
在原生域中添加和更新用户。 添加新用户时需要密码，但更新现有用户时密码是可选的。 要更改用户密码而不更新任何其他字段，请使用更改密码 API。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-put-user
- Parameters:
username (str) – 用户的标识符。注意：用户名长度必须至少为 1 且不超过 507 个字符。 可以包含字母数字字符(a-z, A-Z, 0-9)、空格、标点符号和基本拉丁(ASCII)块中的可打印符号。 不允许前导或尾随空格。
email (None | str) – 用户的电子邮件。
enabled (bool | None) – 指定用户是否启用。
full_name (None | str) – 用户的全名。
password (str | None) – 用户的密码。密码长度必须至少为 6 个字符。 添加用户时，需要 password 或 password_hash 中的一个。 更新现有用户时，密码是可选的，以便可以在不修改用户密码的情况下更新用户的其他字段（如角色）。
password_hash (str | None) – 用户密码的哈希值。必须使用与密码存储配置相同的哈希算法生成。 有关详细信息，请参阅用户缓存和密码哈希算法文档中关于 xpack.security.authc.password_hashing.algorithm 设置的说明。 使用此参数允许客户端出于性能和/或保密原因预先哈希密码。 password 参数和 password_hash 参数不能在同一请求中使用。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 有效值为 true、false 和 wait_for。这些值在索引 API 中具有相同的含义， 但此 API 的默认值为 true。
roles (Sequence[str] | None) – 用户拥有的角色集合。角色决定了用户的访问权限。 要创建没有任何角色的用户，请指定空列表([])。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- query_api_keys(*, aggregations=None, aggs=None, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, typed_keys=None, with_limited_by=None, with_profile_uid=None, body=None)
通过查询查找API密钥。
获取分页的API密钥列表及其信息。 可选择使用查询条件筛选结果。
使用此API需要至少拥有
manage_own_api_key或read_security集群权限。 若仅拥有manage_own_api_key权限，此API仅返回您拥有的API密钥。 若拥有read_security、manage_api_key或更高权限（包括manage_security），此API将返回所有API密钥而不考虑所有权。 参考链接文档查看查找API密钥的示例：https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-query-api-keys
- Parameters:
aggregations (Mapping[str, Mapping[str, Any]] | None) – 对返回的API密钥集合运行的聚合操作。 聚合与查询协同工作，仅对匹配查询的API密钥计算聚合。 仅支持以下聚合类型子集：terms、range、date_range、missing、cardinality、 value_count、composite、filter`和`filters。此外，聚合仅能在查询支持的字段子集上运行。
aggs (Mapping[str, Mapping[str, Any]] | None) – 对返回的API密钥集合运行的聚合操作。 聚合与查询协同工作，仅对匹配查询的API密钥计算聚合。 仅支持以下聚合类型子集：terms、range、date_range、missing、cardinality、 value_count、composite、filter`和`filters。此外，聚合仅能在查询支持的字段子集上运行。
from – 起始文档偏移量，必须非负。默认情况下， 使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
query (Mapping[str, Any] | None) – 用于筛选返回哪些API密钥的查询条件。 若缺失此参数，则等同于`match_all`查询。 支持的查询类型子集包括：match_all、bool、term、terms、match、 ids、prefix、wildcard、exists、range`和`simple_query_string。 可查询与API密钥关联的以下公共信息：id、type、name、creation、 expiration、invalidated、invalidation、username、realm`和`metadata。 注意：与API密钥关联的可查询字符串值在内部被映射为关键字。 因此，若未为`match`查询指定`analyzer`参数，则提供的匹配查询字符串将被解释为单个关键字值， 此时`match`查询等效于`term`查询。
search_after (Sequence[None | bool | float | int | str] | None) – 搜索后定义。
size (int | None) – 返回的结果数量，必须非负。 size`参数可设为`0，此时不返回API密钥匹配项，仅返回聚合结果。 默认情况下，使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – 排序定义。除`id`外，API密钥的所有公共字段均可用于排序。 此外，也可对`_doc`字段应用排序以按索引顺序排列。
typed_keys (bool | None) – 决定响应中聚合名称是否前缀其类型。
with_limited_by (bool | None) – 返回与API密钥关联的所有者用户角色描述符快照。 API密钥的实际权限是其分配角色描述符与所有者用户角色描述符的交集（实际受其限制）。 除非拥有`manage_api_key`或更高权限，否则API密钥无法检索任何API密钥（包括自身）的受限角色描述符。
with_profile_uid (bool | None) – 决定是否同时检索API密钥所有者主体的个人资料UID。 若存在，每个API密钥的`profile_uid`响应字段将返回该UID。
error_trace (bool | None)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- query_role(*, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, body=None)
通过查询查找角色。
以分页方式获取角色信息。 角色管理API通常是管理角色的首选方式，而非基于文件的角色管理。 此查询角色API不会检索角色文件中定义的或内置的角色。 可选择使用查询条件筛选结果，并支持分页和排序。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-query-role
- Parameters:
from – 起始文档偏移量，必须非负。默认情况下， 使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
query (Mapping[str, Any] | None) – 用于筛选返回哪些角色的查询条件。 若缺失此参数，则等同于`match_all`查询。 支持的查询类型子集包括：match_all、bool、term、terms、match、 ids、prefix、wildcard、exists、range`和`simple_query_string。 可查询与角色关联的以下信息：name、description、metadata、 applications.application、applications.privileges`和`applications.resources。
search_after (Sequence[None | bool | float | int | str] | None) – 搜索后定义。
size (int | None) – 返回的结果数量，必须非负。默认情况下， 使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – 排序定义。可对`username`、`roles`或`enabled`字段排序。 此外，也可对`_doc`字段应用排序以按索引顺序排列。
error_trace (bool | None)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- query_user(*, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, with_profile_uid=None, body=None)
通过查询查找用户。
以分页方式获取用户信息。 可选择使用查询条件筛选结果。
注意：与获取用户API不同，内置用户不包含在结果中。 此API仅适用于原生用户。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-query-user
- Parameters:
from – 起始文档偏移量，必须非负。默认情况下， 使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
query (Mapping[str, Any] | None) – 用于筛选返回哪些用户的查询条件。 若缺失此参数，则等同于`match_all`查询。 支持的查询类型子集包括：match_all、bool、term、terms、match、 ids、prefix、wildcard、exists、range`和`simple_query_string。 可查询与用户关联的以下信息：username、roles、enabled、full_name`和`email。
search_after (Sequence[None | bool | float | int | str] | None) – 搜索后定义
size (int | None) – 返回的结果数量，必须非负。默认情况下， 使用`from`和`size`参数无法分页超过10,000条结果。 如需分页更多结果，请使用`search_after`参数。
sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – 排序定义。可排序字段包括：username、roles、enabled。 此外，也可对`_doc`字段应用排序以按索引顺序排列。
with_profile_uid (bool | None) – 决定是否检索用户个人资料UID（若存在）。
error_trace (bool | None)
from_ (int | None)
human (bool | None)
pretty (bool | None)
- Return type:
- saml_authenticate(*, content=None, ids=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)
SAML认证。
向Elasticsearch提交SAML响应消息以供消费。
注意：此API供Kibana以外的自定义Web应用程序使用。 若您使用Kibana，请参考Elastic Stack上配置SAML单点登录的文档。
提交的SAML消息可以是：
- 对先前通过SAML准备认证API创建的认证请求的响应
- 在IdP发起的单点登录(SSO)流程中的主动SAML消息
无论哪种情况，SAML消息都需是Base64编码的XML文档，且根元素为
<Response>。验证成功后，Elasticsearch会返回Elasticsearch内部访问令牌和刷新令牌，后续可用于认证。 此API端点本质上是将IdP中表示成功认证的SAML响应交换为可用于Elasticsearch认证的访问令牌和刷新令牌。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-authenticate
- saml_complete_logout(*, ids=None, realm=None, content=None, error_trace=None, filter_path=None, human=None, pretty=None, query_string=None, body=None)
完成SAML注销。
验证从SAML IdP发送的注销响应。
注意：此API供Kibana以外的自定义Web应用程序使用。 若您使用Kibana，请参考Elastic Stack上配置SAML单点登录的文档。
SAML IdP在处理SP发起的SAML单点注销后，可能会向SP发送注销响应。 此API通过确保内容相关并验证签名来验证响应。 若验证成功则返回空响应。 响应可由IdP通过HTTP-Redirect或HTTP-Post绑定发送。 API调用者必须相应准备请求以便此API能处理任一方式。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-complete-logout
- Parameters:
ids (str | Sequence[str] | None) – JSON数组，包含API调用者为当前用户持有的所有有效SAML请求ID。
realm (str | None) – Elasticsearch中SAML领域的名称，其配置将用于验证注销响应。
content (str | None) – 若SAML IdP通过HTTP-Post绑定发送注销响应， 此字段必须设置为注销响应中SAMLResponse表单参数的值。
query_string (str | None) – 若SAML IdP通过HTTP-Redirect绑定发送注销响应， 此字段必须设置为重定向URI的查询字符串。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- saml_invalidate(*, query_string=None, acs=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, body=None)
使SAML失效。
向Elasticsearch提交SAML LogoutRequest消息进行处理。
注意：此API专供Kibana以外的自定义Web应用程序使用。 如果您正在使用Kibana，请参阅Elastic Stack上配置SAML单点登录的文档。
注销请求来自SAML IdP在IdP发起的单点注销过程中。 自定义Web应用程序可以使用此API让Elasticsearch处理
LogoutRequest。 成功验证请求后，Elasticsearch将使与该特定SAML主体对应的访问令牌和刷新令牌失效，并提供包含SAML LogoutResponse消息的URL。 因此用户可以被重定向回其IdP。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-invalidate
- Parameters:
query_string (str | None) – 用户被SAML IdP重定向以发起单点注销的URL查询部分。此查询应包含 名为`SAMLRequest`的单个参数，其中包含经过压缩和Base64编码的SAML注销请求。 如果SAML IdP已签署注销请求，URL应包含两个额外参数`SigAlg`和`Signature`， 分别包含用于签名的算法和签名值本身。为了使Elasticsearch能够验证IdP的签名， `query_string`字段的值必须与浏览器提供的字符串完全匹配。客户端应用程序不得尝试 以任何方式解析或处理该字符串。
acs (str | None) – 与Elasticsearch中SAML领域匹配的断言消费者服务URL。必须指定此参数或 `realm`参数。
realm (str | None) – Elasticsearch中SAML领域的名称配置。必须指定此参数或`acs`参数。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- saml_logout(*, token=None, error_trace=None, filter_path=None, human=None, pretty=None, refresh_token=None, body=None)
SAML注销。
提交使访问令牌和刷新令牌失效的请求。
注意：此API专供Kibana以外的自定义Web应用程序使用。 如果您正在使用Kibana，请参阅Elastic Stack上配置SAML单点登录的文档。
此API将使通过SAML认证API为用户生成的令牌失效。 如果Elasticsearch中的SAML领域配置得当且SAML IdP支持此功能，Elasticsearch响应将包含一个URL，将用户重定向到包含SAML注销请求的IdP（启动SP发起的SAML单点注销）。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-saml-logout
- Parameters:
- Return type:
- saml_prepare_authentication(*, acs=None, error_trace=None, filter_path=None, human=None, pretty=None, realm=None, relay_state=None, body=None)
准备SAML认证。
基于Elasticsearch中相应SAML领域的配置，创建SAML认证请求(
<AuthnRequest>)作为URL字符串。注意：此API专供Kibana以外的自定义Web应用程序使用。 如果您正在使用Kibana，请参阅Elastic Stack上配置SAML单点登录的文档。
此API返回指向SAML身份提供者的URL。 您可以使用此URL重定向用户浏览器以继续认证过程。 URL包含名为
SAMLRequest的单个参数，其中包含经过压缩和Base64编码的SAML认证请求。 如果配置要求SAML认证请求应被签名，则URL还有两个额外参数SigAlg和Signature。 这些参数包含用于签名的算法和签名值本身。 它还返回一个随机字符串，唯一标识此SAML认证请求。 此API的调用者需要存储此标识符，因为在认证过程的后续步骤中需要使用它。- Parameters:
acs (str | None) – 与Elasticsearch中SAML领域匹配的断言消费者服务URL。该领域用于生成认证 请求。必须指定此参数或`realm`参数。
realm (str | None) – Elasticsearch中SAML领域的名称，其配置用于生成认证请求。必须指定此 参数或`acs`参数。
relay_state (str | None) – 将包含在此API返回的重定向URL中作为`RelayState`查询参数的字符串。 如果认证请求被签名，此值将用作签名计算的一部分。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- saml_service_provider_metadata(*, realm_name, error_trace=None, filter_path=None, human=None, pretty=None)
创建SAML服务提供者元数据。
为SAML 2.0服务提供者生成元数据。
SAML 2.0规范提供了一种机制，使服务提供者可以使用元数据文件描述其功能和配置。 此API基于Elasticsearch中SAML领域的配置生成服务提供者元数据。
- suggest_user_profiles(*, data=None, error_trace=None, filter_path=None, hint=None, human=None, name=None, pretty=None, size=None, body=None)
建议用户配置文件。
获取符合指定搜索条件的用户配置文件建议。
注意：用户配置文件功能专为Kibana和Elastic的可观测性、企业搜索及安全解决方案设计。 个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或删除此功能的权利，恕不另行通知。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-suggest-user-profiles
- Parameters:
data (str | Sequence[str] | None) – 配置文件文档`data`字段的逗号分隔过滤器列表。要返回所有内容，请使用`data=*`。 要返回内容子集，请使用`data=<key>`检索嵌套在指定`<key>`下的内容。 默认情况下，API不返回`data`内容。同时将`data`指定为查询参数和请求体字段是错误的。
hint (Mapping[str, Any] | None) – 额外的搜索条件以提高建议结果的相关性。匹配指定提示的配置文件在响应中排名更高。 只要配置文件匹配`name`字段查询，不匹配提示的配置文件也不会被排除在响应之外。
name (str | None) – 用于匹配用户配置文件文档中名称相关字段的查询字符串。名称相关字段包括用户的 username、full_name`和`email。
size (int | None) – 要返回的配置文件数量。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- update_api_key(*, id, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, role_descriptors=None, body=None)
更新API密钥。
更新现有API密钥的属性。 此API支持更新API密钥的访问范围、过期时间和元数据。
使用此API需要至少拥有
manage_own_api_key集群权限。 用户只能更新自己创建或被授予的API密钥。 要更新其他用户的API密钥，需使用run_as功能代表其他用户提交请求。重要提示：不能使用API密钥作为此API的身份验证凭证，必须提供所有者用户的凭据。
此API用于更新通过创建API密钥或授予API密钥API生成的密钥。 如需对多个API密钥应用相同更新，可使用批量更新API密钥API以减少开销。 无法更新已过期的API密钥或已被失效API密钥API作废的密钥。
API密钥的访问范围由请求中指定的
role_descriptors和请求时所有者用户权限的快照共同决定。 所有者权限快照会在每次调用时自动更新。重要提示：即使请求中未指定
role_descriptors，调用此API仍可能改变API密钥的访问范围。 这种情况会在API密钥创建或上次修改后所有者用户权限发生变化时发生。https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-api-key
- Parameters:
id (str) – 要更新的API密钥ID。
expiration (str | Literal[-1] | ~typing.Literal[0] | None) – API密钥的过期时间。默认情况下API密钥永不过期。 可省略此属性以保持原过期时间不变。
metadata (Mapping[str, Any] | None) – 要与API密钥关联的任意元数据。 支持嵌套数据结构。元数据对象中以下划线`_`开头的键为系统保留字段。 指定时将完全替换之前关联的元数据。
role_descriptors (Mapping[str, Mapping[str, Any]] | None) – 分配给此API密钥的角色描述符。 API密钥的有效权限是其分配权限与所有者用户权限时间点快照的交集。 可通过此参数分配新权限。要移除已分配权限，可传入空的`role_descriptors`参数（即空对象`{}`）。 若API密钥无分配权限，则继承所有者用户的完整权限。无论是否提供`role_descriptors`参数， 所有者权限快照都会更新。角色描述符结构与创建API密钥API的请求相同。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- update_cross_cluster_api_key(*, id, access=None, error_trace=None, expiration=None, filter_path=None, human=None, metadata=None, pretty=None, body=None)
更新跨集群API密钥。
更新现有跨集群API密钥的属性，该密钥用于基于API密钥的远程集群访问。
使用此API需要至少拥有
manage_security集群权限。 用户只能更新自己创建的API密钥。 要更新其他用户的API密钥，需使用run_as功能代表其他用户提交请求。重要提示：不能使用API密钥作为此API的身份验证凭证，必须提供所有者用户的凭据。
无法更新已过期的API密钥或已被失效API密钥API作废的密钥。
此API支持更新API密钥的访问范围、元数据和过期时间。 所有者用户信息（如
username和realm）也会在每次调用时自动更新。注意：此API不能更新REST API密钥，应通过更新API密钥或批量更新API密钥API进行更新。
要了解如何使用此API，请参阅更新跨集群API密钥API示例页面。
- Parameters:
id (str) – 要更新的跨集群API密钥ID。
access (Mapping[str, Any] | None) – 授予此API密钥的访问权限。访问权限由跨集群搜索和跨集群复制的权限组成。 必须至少指定其中一项。指定时将完全替换之前分配的访问权限。
expiration (str | Literal[-1] | ~typing.Literal[0] | None) – API密钥的过期时间。默认情况下API密钥永不过期。 可省略此属性以保持原值不变。
metadata (Mapping[str, Any] | None) – 要与API密钥关联的任意元数据。 支持嵌套数据结构。元数据对象中以下划线`_`开头的键为系统保留字段。 指定时将完全替换之前关联的元数据。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- update_settings(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None, security=None, security_profile=None, security_tokens=None, timeout=None, body=None)
更新安全索引设置。
更新安全内部索引（
.security及相关索引）的用户可配置设置。仅允许修改部分设置，包括index.auto_expand_replicas和index.number_of_replicas。注意：若设置了
index.auto_expand_replicas，更新时将忽略index.number_of_replicas。如果系统未使用特定索引却提供了其设置，请求将被拒绝。 此API尚不支持在索引使用前配置其设置。
https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-update-settings
- Parameters:
master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待连接主节点的时间。 若在超时前未收到响应，请求将失败并返回错误。
security (Mapping[str, Any] | None) – 用于大多数安全配置的索引设置， 包括原生领域用户和通过API配置的角色。
security_profile (Mapping[str, Any] | None) – 用于存储配置文件信息的索引设置。
timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待响应的时间。若在超时前未收到响应， 请求将失败并返回错误。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type:
- update_user_profile_data(*, uid, data=None, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, labels=None, pretty=None, refresh=None, body=None)
更新用户配置文件数据。
更新与唯一ID关联的用户配置文件的特定数据。
注意：用户配置文件功能专为Kibana及Elastic的可观测性、企业搜索和安全解决方案设计。 个人用户和外部应用程序不应直接调用此API。 Elastic保留在未来版本中更改或移除该功能的权利，恕不另行通知。
使用此API需要具备以下任一权限：
manage_user_profile集群权限- 请求中引用命名空间的
update_profile_data全局权限
此API使用JSON对象更新现有用户配置文件文档的
labels和data字段。 新键及其值会被添加到配置文件中，冲突的键将被请求中的数据替换。标签和数据内容都按顶级字段划分命名空间。
update_profile_data全局权限仅授予更新允许命名空间的权限。- Parameters:
uid (str) – 用户配置文件的唯一标识符。
data (Mapping[str, Any] | None) – 要与用户配置文件关联的非可搜索数据。 此字段支持嵌套数据结构。在`data`对象中，顶级键不能以下划线(_)开头或包含点号(.)。 数据对象不可搜索，但可通过获取用户配置文件API检索。
if_primary_term (int | None) – 仅当文档具有此主术语时执行操作。
if_seq_no (int | None) – 仅当文档具有此序列号时执行操作。
labels (Mapping[str, Any] | None) – 要与用户配置文件关联的可搜索数据。 此字段支持嵌套数据结构。在labels对象中，顶级键不能以下划线(_)开头或包含点号(.)。
refresh (bool | str | Literal['false', 'true', 'wait_for'] | None) – 若为’true’，Elasticsearch会刷新受影响分片使操作对搜索可见。 若为’wait_for’，则等待刷新使操作对搜索可见。若为’false’，不执行刷新操作。
error_trace (bool | None)
human (bool | None)
pretty (bool | None)
- Return type: