› › ›

API для подбора профилей пользователей

Функция профилей пользователей предназначена только для использования Kibana и решениями Elastic по наблюдаемости, поиску в корпоративной среде и Elastic Security. Отдельные пользователи и внешние приложения не должны вызывать этот API напрямую. Elastic оставляет за собой право изменить или удалить эту функцию в будущих выпусках без предварительного уведомления.

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

Запрос

GET /_security/profile/_suggest

POST /_security/profile/_suggest

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

Для использования этого API необходимо иметь как минимум read_security право доступа к кластеру (или более широкое право, такое как manage_user_profile или manage_security).

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

data: (Необязательно, строка) Список фильтров, разделенных запятыми, для поля data документа профиля. Для возвращения всего содержимого используйте data=*. Для возвращения подмножества содержимого используйте data=<key>, чтобы получить содержимое, вложенное под указанным <key>. По умолчанию не возвращает никакого содержимого.

Тело запроса

name: (Необязательно, строка) Строка запроса, используемая для сопоставления полей, связанных с именем, в документах профилей пользователей. Поля, связанные с именем, это имя пользователя, full_name и email.
size: (Необязательно, целое число) Количество профилей для возврата. По умолчанию 10.
data: (Необязательно, строка) Список фильтров, разделенных запятыми, для поля data документа профиля. Работает аналогично параметру запроса data.

Указание data как параметра запроса и поля тела запроса является ошибкой.

hint

(Необязательно, объект) Дополнительные критерии поиска для повышения релевантности результата подбора. Профиль, соответствующий указанному подсказке, ранжируется выше в ответе. Но несоответствие подсказке не исключает профиль из ответа, если он соответствует запросу поля name.

Свойства hint:

uids: (Необязательно, список строк) Список идентификаторов профилей для сопоставления.
labels: (Необязательно, объект) Одна пара "ключ-значение" для сопоставления с разделом labels профиля. Ключ должен быть строкой, а значение должно быть строкой или списком строк. Профиль считается совпадающим, если он соответствует по крайней мере одной из строк.

Тело ответа

total: (объект) Метаданные о количестве совпадающих профилей.
took: (целое число) Миллисекунды, которые потребовались Elasticsearch для выполнения запроса.
profiles: (массив объектов) Список документов профилей, отсортированных по релевантности, которые соответствуют критериям поиска.

Примеры

Следующий запрос получает предложения по документам профиля с полями, связанными с именем, соответствующими jack. Он указывает подсказки uids и labels для лучшей релевантности:

resp = client.security.suggest_user_profiles(
    name="jack",
    hint={
        "uids": [
            "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
            "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        ],
        "labels": {
            "direction": [
                "north",
                "east"
            ]
        }
    },
)
print(resp)

const response = await client.security.suggestUserProfiles({
  name: "jack",
  hint: {
    uids: [
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
    ],
    labels: {
      direction: ["north", "east"],
    },
  },
});
console.log(response);

POST /_security/profile/_suggest
{
  "name": "jack",  
  "hint": {
    "uids": [  
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
    ],
    "labels": {
      "direction": ["north", "east"]  
    }
  }
}

	Поля, связанные с именем профиля, должны соответствовать `jack`, чтобы он был включен в ответ.
	Подсказка `uids` включает идентификаторы профилей для пользователей `jackspa` и `jacknich`.
	Подсказка `labels` ранжирует профили выше, если метка `direction` соответствует либо `north`, либо `east`.

API возвращает:

{
  "took": 30,
  "total": {
    "value": 3,
    "relation": "eq"
  },
  "profiles": [
    {
      "uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
      "user": {
        "username": "jacknich",    
        "roles": [ "admin", "other_role1" ],
        "realm_name": "native",
        "email" : "jacknich@example.com",
        "full_name": "Jack Nicholson"
      },
      "labels": {
        "direction": "north"
      },
      "data": {}
    },
    {
      "uid": "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "user": {
        "username": "jackspa",    
        "roles": [ "user" ],
        "realm_name": "native",
        "email" : "jackspa@example.com",
        "full_name": "Jack Sparrow"
      },
      "labels": {
        "direction": "south"
      },
      "data": {}
    },
    {
      "uid": "u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0",
      "user": {
        "username": "jackrea",    
        "roles": [ "admin" ],
        "realm_name": "native",
        "email" : "jackrea@example.com",
        "full_name": "Jack Reacher"
      },
      "labels": {
        "direction": "west"
      },
      "data": {}
    }
  ]
}

	Пользователь `jacknich` ранжируется выше всего, потому что профиль соответствует подсказкам `uids` и `labels`
	Пользователь `jackspa` ранжируется вторым, потому что профиль соответствует только подсказке `uids`
	Пользователь `jackrea` ранжируется ниже всего, потому что профиль не соответствует никаким подсказкам. Однако он не исключается из ответа, потому что он соответствует запросу поля `name`.

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