Rank - Rank
A Personalizer rank request.
POST {Endpoint}/personalizer/v1.0/rank
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
Endpoint
|
path | True |
string |
Supported Cognitive Services endpoint. |
Request Header
Name | Required | Type | Description |
---|---|---|---|
Ocp-Apim-Subscription-Key | True |
string |
Request Body
Name | Required | Type | Description |
---|---|---|---|
actions | True |
The set of actions the Personalizer service can pick from. The set should not contain more than 50 actions. The order of the actions does not affect the rank result but the order should match the sequence your application would have used to display them. |
|
contextFeatures |
object[] |
Features of the context used for Personalizer as a dictionary of dictionaries. This depends on the application, and typically includes features about the current user, their device, profile information, data about time and date, etc. |
|
deferActivation |
boolean |
Send false if the user will see the rank results, therefore Personalizer will expect a Reward call, otherwise it will assign the default Reward to the event. Send true if it is possible the user will not see the rank results, because the page is rendering later, or the Rank results may be overridden by code further downstream. |
|
eventId |
string |
Optionally pass an eventId that uniquely identifies this Rank event. If null, the service generates a unique eventId. The eventId will be used for associating this request with its reward, as well as seeding the pseudo-random generator when making a Personalizer call. |
|
excludedActions |
string[] |
The set of action ids to exclude from ranking. |
Responses
Name | Type | Description |
---|---|---|
201 Created |
Success |
|
Other Status Codes |
Invalid rank request. |
Security
Ocp-Apim-Subscription-Key
Type:
apiKey
In:
header
Examples
Successful Rank request
Sample Request
POST {Endpoint}/personalizer/v1.0/rank
{
"contextFeatures": [
{
"timeOfDay": "Morning"
}
],
"actions": [
{
"id": "NewsArticle",
"features": [
{
"type": "News"
}
]
},
{
"id": "SportsArticle",
"features": [
{
"type": "Sports"
}
]
},
{
"id": "EntertainmentArticle",
"features": [
{
"type": "Entertainment"
}
]
}
],
"excludedActions": [
"SportsArticle"
],
"eventId": "75269AD0-BFEE-4598-8196-C57383D38E10",
"deferActivation": false
}
Sample Response
{
"ranking": [
{
"id": "EntertainmentArticle",
"probability": 0.8
},
{
"id": "SportsArticle",
"probability": 0
},
{
"id": "NewsArticle",
"probability": 0.2
}
],
"eventId": "75269AD0-BFEE-4598-8196-C57383D38E10",
"rewardActionId": "EntertainmentArticle"
}
Definitions
Name | Description |
---|---|
Error |
High level error code. |
Error |
Used to return an error to the client |
Internal |
An object containing more specific information than the parent object about the error. |
Personalizer |
The error object. |
Rankable |
An action with it's associated features used for ranking. |
Ranked |
A ranked action with its resulting probability. |
Rank |
Request a set of actions to be ranked by the Personalizer service. |
Rank |
A resulting ordered list of actions that result from a rank request. |
ErrorCode
High level error code.
Name | Type | Description |
---|---|---|
BadRequest |
string |
Request could not be understood by the server. |
InternalServerError |
string |
A generic error has occurred on the server. |
ResourceNotFound |
string |
Requested resource does not exist on the server. |
ErrorResponse
Used to return an error to the client
Name | Type | Description |
---|---|---|
error |
The error object. |
InternalError
An object containing more specific information than the parent object about the error.
Name | Type | Description |
---|---|---|
code |
string |
Detailed error code. |
innererror |
The error object. |
PersonalizerError
The error object.
Name | Type | Description |
---|---|---|
code |
High level error code. |
|
details |
An array of details about specific errors that led to this reported error. |
|
innerError |
Finer error details. |
|
message |
string |
A message explaining the error reported by the service. |
target |
string |
Error source element. |
RankableAction
An action with it's associated features used for ranking.
Name | Type | Description |
---|---|---|
features |
object[] |
List of dictionaries containing features. |
id |
string |
Id of the action. |
RankedAction
A ranked action with its resulting probability.
Name | Type | Description |
---|---|---|
id |
string |
Id of the action |
probability |
number |
Probability of the action |
RankRequest
Request a set of actions to be ranked by the Personalizer service.
Name | Type | Default Value | Description |
---|---|---|---|
actions |
The set of actions the Personalizer service can pick from. The set should not contain more than 50 actions. The order of the actions does not affect the rank result but the order should match the sequence your application would have used to display them. |
||
contextFeatures |
object[] |
Features of the context used for Personalizer as a dictionary of dictionaries. This depends on the application, and typically includes features about the current user, their device, profile information, data about time and date, etc. |
|
deferActivation |
boolean |
False |
Send false if the user will see the rank results, therefore Personalizer will expect a Reward call, otherwise it will assign the default Reward to the event. Send true if it is possible the user will not see the rank results, because the page is rendering later, or the Rank results may be overridden by code further downstream. |
eventId |
string |
Optionally pass an eventId that uniquely identifies this Rank event. If null, the service generates a unique eventId. The eventId will be used for associating this request with its reward, as well as seeding the pseudo-random generator when making a Personalizer call. |
|
excludedActions |
string[] |
The set of action ids to exclude from ranking. |
RankResponse
A resulting ordered list of actions that result from a rank request.
Name | Type | Description |
---|---|---|
eventId |
string |
The eventId for the round trip from request to response. |
ranking |
The calculated ranking for the current request. |
|
rewardActionId |
string |
The action chosen by the Personalizer service. This is the action for which to report the reward. This might not be the first found in 'ranking' if an action in the request in first position was part of the excluded ids. |