New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 获取角色 API 获取服务帐户 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›安全 API

查询角色 API

编辑

查询角色 API

编辑

以查询 DSL 方式检索角色，并支持分页。

请求

编辑

GET /_security/_query/role

POST /_security/_query/role

先决条件

编辑
  • 要使用此 API，您必须至少拥有 read_security 集群特权。

描述

编辑

角色管理 API 通常是管理角色的首选方式，而不是使用基于文件的角色管理。查询角色 API 不会检索在角色文件中定义的角色，也不会检索内置角色。您可以选择使用查询来过滤结果。此外，结果可以分页和排序。

请求体

编辑

您可以在请求体中指定以下参数

query

（可选，字符串）一个查询，用于过滤要返回的角色。该查询支持查询类型的子集，包括match_all、bool、term、terms、match、ids、prefix、wildcard、exists、range和simple query string。

您可以查询与角色关联的以下值。

query 的有效值
name
（关键词）角色的名称。
description
（文本）角色的描述。
metadata
（扁平）与角色关联的元数据字段，例如metadata.app_tag。请注意，元数据在内部被索引为扁平字段类型。这意味着在查询和排序时，所有子字段都像keyword字段一样。这也意味着不可能使用通配符模式（例如 metadata.field*）引用元数据字段的子集，即使对于支持字段名称模式的查询类型也是如此。最后，当简单地提及metadata字段时（即，后面没有跟任何点和子字段名称），可以一起搜索所有元数据字段。
applications

角色授予的应用程序权限列表。

application
（关键词）与权限和资源关联的应用程序的名称。
privileges
（关键词）角色授予的权限的名称。
resources
（关键词）权限适用的资源。
from

（可选，整数）起始文档偏移量。需要是非负数，默认值为 0。

默认情况下，您不能使用 from 和 size 参数翻阅超过 10,000 个命中。要翻阅更多命中，请使用 search_after 参数。

size

（可选，整数）要返回的命中数。不能为负数，默认值为 10。

默认情况下，您不能使用 from 和 size 参数翻阅超过 10,000 个命中。要翻阅更多命中，请使用 search_after 参数。

sort
（可选，对象）排序定义。您可以根据 username、roles 或 enabled 进行排序。此外，排序也可以应用于 _doc 字段以按索引顺序排序。
search_after
（可选，数组）之后搜索定义。

响应体

编辑

此 API 返回以下顶级字段

total
找到的角色总数。
count
响应中返回的角色数。
roles
与查询匹配的角色列表。返回的角色格式是角色定义格式的扩展。它添加了 transient_metadata.enabled 和 _sort 字段。如果角色自动禁用，例如当角色授予安装的许可证不允许的权限时，transient_metadata.enabled 设置为 false。_sort 在搜索查询按某些字段排序时出现。它包含用于排序的值数组。

示例

编辑

以下请求列出所有角色，按角色名称排序

resp = client.security.query_role(
    sort=[
        "name"
    ],
)
print(resp)
const response = await client.security.queryRole({
  sort: ["name"],
});
console.log(response);
POST /_security/_query/role
{
    "sort": ["name"]
}
Copy as curlTry in Elastic 

成功的调用返回一个 JSON 结构，其中包含为一个或多个角色检索的信息

{
    "total": 2,
    "count": 2,
    "roles": [ 
        {
          "name" : "my_admin_role",
          "cluster" : [
            "all"
          ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [
            "other_user"
          ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants full access to all management features within the cluster.",
          "_sort" : [
            "my_admin_role"
          ]
        },
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies.",
          "_sort" : [
            "my_user_role"
          ]
        }
    ]
}

为此请求检索的角色列表

同样，以下请求可用于查询仅具有描述的用户访问角色

resp = client.security.query_role(
    query={
        "match": {
            "description": {
                "query": "user access"
            }
        }
    },
    size=1,
)
print(resp)
const response = await client.security.queryRole({
  query: {
    match: {
      description: {
        query: "user access",
      },
    },
  },
  size: 1,
});
console.log(response);
POST /_security/_query/role
{
  "query": {
    "match": {
      "description": {
        "query": "user access"
      }
    }
  },
  "size": 1 
}
Copy as curlTry in Elastic 

仅返回最佳匹配的角色

 
{
    "total": 2,
    "count": 1,
    "roles": [
        {
          "name" : "my_user_role",
          "cluster" : [ ],
          "indices" : [
            {
              "names" : [
                "index1",
                "index2"
              ],
              "privileges" : [
                "all"
              ],
              "field_security" : {
                "grant" : [
                  "title",
                  "body"
                ]
              },
              "allow_restricted_indices" : false
            }
          ],
          "applications" : [ ],
          "run_as" : [ ],
          "metadata" : {
            "version" : 1
          },
          "transient_metadata" : {
            "enabled" : true
          },
          "description" : "Grants user access to some indicies."
        }
    ]
}
« 获取角色 API 获取服务帐户 API »

On this page

Was this helpful?
Feedback