› › ›

API запроса ролей

Возвращает роли с помощью Query 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.

По умолчанию вы не можете просматривать более 10 000 совпадений с помощью параметров from и size. Чтобы просмотреть больше совпадений, используйте параметр search_after.

size

(Необязательно, целое число) Количество совпадений для возврата. Не должно быть отрицательным и по умолчанию равно 10.

sort

(Необязательно, объект) Определение сортировки. Вы можете сортировать по полю username, roles или enabled. Кроме того, сортировка также может быть применена к полю _doc для сортировки по порядку индексов.

search_after

(Необязательно, массив) Определение поиска после.

Тело ответа

Этот API возвращает следующие поля верхнего уровня:

total: Общее количество найденных ролей.
count: Количество ролей, возвращённых в ответе.
roles: Список ролей, соответствующих запросу. Формат возвращаемой роли — расширение формата определения роли. Он добавляет поля transient_metadata.enabled и _sort. transient_metadata.enabled устанавливается в false, если роль автоматически отключена, например, когда роль предоставляет привилегии, которые не разрешены установленной лицензией. _sort присутствует, когда запрос поиска сортирует по какому-либо полю. Он содержит массив значений, которые использовались для сортировки.

Примеры

Следующий запрос перечисляет все роли, отсортированные по имени роли:

POST /_security/_query/role
{
    "sort": ["name"]
}

Успешный вызов возвращает 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 
}

Возвращается только наиболее подходящая роль

{
    "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."
        }
    ]
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-query-role.html