› › ›

API запроса пользователя

Возвращает локальных пользователей с Query DSL в страничном формате.

В отличие от API получения пользователя, встроенные пользователи исключаются из результата. Этот API предназначен только для локальных пользователей.

Запрос

GET /_security/_query/user

POST /_security/_query/user

Предварительные условия

Для использования этого API необходимо обладать по крайней мере правом доступа read_security к кластеру.

Описание

Используйте этот API для получения пользователей, управляемых локальной областью, в страничном формате. Вы можете дополнительно фильтровать результаты с помощью запроса.

Тело запроса

В теле запроса можно указать следующие параметры:

query

(Необязательно, строка) Запрос для фильтрации возвращаемых пользователей. Запрос поддерживает подмножество типов запросов, включая match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range и simple query string.

Вы можете запросить следующие публичные значения, связанные с пользователем.

Допустимые значения для query

username: Идентификатор пользователя.
roles: Массив имён ролей ролей, назначенных пользователю.
full_name: Полное имя пользователя.
email: Электронная почта пользователя.
enabled: Указывает, включён ли пользователь.

from

(Необязательно, целое число) Смещение начального документа. Должно быть неотрицательным и по умолчанию равно 0.

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

size

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

sort

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

search_after

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

Параметры запроса

with_profile_uid: (Необязательно, булево) Определяет, необходимо ли получить профиль пользователя uid, если он существует, для пользователей. По умолчанию false.

Тело ответа

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

total: Общее количество найденных пользователей.
count: Количество пользователей, возвращённых в ответе.
users: Список пользователей, соответствующих запросу.

Примеры

Следующий запрос перечисляет всех пользователей, предполагая, что у вас есть право read_security:

resp = client.perform_request(
    "GET",
    "/_security/_query/user",
)
print(resp)

const response = await client.security.queryUser();
console.log(response);

GET /_security/_query/user

Успешный вызов возвращает JSON-структуру, содержащую информацию об одном или нескольких пользователях:

{
    "total": 2,
    "count": 2,
    "users": [ 
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        },
        {
            "username": "sandrakn",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Sandra Knight",
            "email": "sandrakn@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}

Список пользователей, полученных для этого запроса

Если вы создаёте пользователя со следующими данными:

resp = client.security.put_user(
    username="jacknich",
    password="l0ng-r4nd0m-p@ssw0rd",
    roles=[
        "admin",
        "other_role1"
    ],
    full_name="Jack Nicholson",
    email="jacknich@example.com",
    metadata={
        "intelligence": 7
    },
)
print(resp)

const response = await client.security.putUser({
  username: "jacknich",
  password: "l0ng-r4nd0m-p@ssw0rd",
  roles: ["admin", "other_role1"],
  full_name: "Jack Nicholson",
  email: "jacknich@example.com",
  metadata: {
    intelligence: 7,
  },
});
console.log(response);

POST /_security/user/jacknich
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "jacknich@example.com",
  "metadata" : {
    "intelligence" : 7
  }
}

Успешный вызов возвращает JSON-структуру:

{
  "created": true
}

Используйте информацию о пользователе для получения пользователя с помощью запроса:

resp = client.perform_request(
    "POST",
    "/_security/_query/user",
    headers={"Content-Type": "application/json"},
    body={
        "query": {
            "prefix": {
                "roles": "other"
            }
        }
    },
)
print(resp)

const response = await client.security.queryUser({
  query: {
    prefix: {
      roles: "other",
    },
  },
});
console.log(response);

POST /_security/_query/user
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}

Успешный вызов возвращает JSON-структуру для пользователя:

{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}

Для получения пользователя profile_uid в качестве части ответа:

resp = client.perform_request(
    "POST",
    "/_security/_query/user",
    params={
        "with_profile_uid": "true"
    },
    headers={"Content-Type": "application/json"},
    body={
        "query": {
            "prefix": {
                "roles": "other"
            }
        }
    },
)
print(resp)

const response = await client.security.queryUser({
  with_profile_uid: "true",
  query: {
    prefix: {
      roles: "other",
    },
  },
});
console.log(response);

POST /_security/_query/user?with_profile_uid=true
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}

{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        }
    ]
}

Используйте запрос bool для выполнения сложных логических условий и используйте from, size, sort для помощи в страничном отображении результата:

POST /_security/_query/user
{
  "query": {
    "bool": {
      "must": [
        {
          "wildcard": {
            "email": "*example.com" 
          }
        },
        {
          "term": {
            "enabled": true 
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "roles": "*other*" 
          }
        }
      ]
    }
  },
  "from": 1, 
  "size": 2, 
  "sort": [
    { "username": { "order": "desc"} } 
  ]
}

	Адрес электронной почты должен заканчиваться на `example.com`
	Пользователь должен быть включен
	Результат будет отфильтрован, чтобы содержать только пользователей с хотя бы одной ролью, которая содержит подстроку `other`
	Смещение для начала результата поиска — второй (с нулевым индексом) пользователь
	Размер страницы ответа — 2 пользователя
	Результат отсортирован по `username` в порядке убывания

Ответ содержит список соответствующих пользователей вместе с их значениями сортировки:

{
    "total": 5,
    "count": 2,
    "users": [
        {
            "username": "ray",
            "roles": [
                "other_role3"
            ],
            "full_name": "Ray Nicholson",
            "email": "rayn@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "ray" 
            ]
        },
        {
            "username": "lorraine",
            "roles": [
                "other_role3"
            ],
            "full_name": "Lorraine Nicholson",
            "email": "lorraine@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "lorraine"
            ]
        }
    ]
}

Значение сортировки — username

© 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-user.html