Suggest user profile API
editSuggest user profile API
editThis functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.
Get suggestions for user profiles that match specified search criteria.
Prerequisites
editTo use this API, you must have the manage_user_profile cluster privilege.
Query parameters
edit-
data -
(Optional, string) Comma-separated list of filters for the
datafield of the profile document. To return all content, usedata=*. To return a subset of content, usedata=<key>to retrieve the content nested under the specified<key>. Defaults to returning no content.
Request body
edit-
name -
(Optional, string)
Query string used to match name-related fields in user profile documents. Name-related fields are the user’s
username,full_nameandemail. -
size -
(Optional, integer)
Number of profiles to return. Defaults to
10. -
data -
(Optional, string)
Comma-separated list of filters for the
datafield of the profile document. It works the same way as thedataquery parameter.
It is an error to specify data as both the query parameter and the request body field.
-
hint -
(Optional, object) Extra search criteria to improve relevance of the suggestion result. A profile matching the specified hint is ranked higher in the response. But not-matching the hint does not exclude a profile from the response as long as it matches the
namefield query.Properties ofhint:-
uids - (Optional, list of strings) A list of Profile UIDs to match against.
-
labels -
(Optional, object)
A single key-value pair to match against the
labelssection of a profile. The key must be a string and the value must be either a string or a list of strings. A profile is considered matching if it matches at least one of the strings.
-
Response body
edit-
total - (object) Metadata about the number of matching profiles.
-
took - (integer) Milliseconds it took Elasticsearch to execute the request.
-
profiles - (array of objects) List of profile documents, ordered by relevance, that match the search criteria.
Examples
editThe following request get suggestions for profile documents with name-related fields
matching jack. It specifies both uids and labels hints for better relevance:
POST /_security/profile/_suggest
{
"name": "jack",
"hint": {
"uids": [
"u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
"u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
],
"labels": {
"direction": ["north", "east"]
}
}
}
|
A profile’s name-related fields must match |
|
|
The |
|
|
The |
The API returns:
{
"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": {}
}
]
}
|
User |
|
|
User |
|
|
User |