Rank - Rank

Reference

Service:: Cognitive Services - Personalizer

API Version:: v1.0

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	RankableAction[]	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	RankResponse	Success
Other Status Codes	ErrorResponse	Invalid rank request.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful Rank request

Sample Request

HTTP

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

Status code:: 201

{
  "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
ErrorCode	High level error code.
ErrorResponse	Used to return an error to the client
InternalError	An object containing more specific information than the parent object about the error.
PersonalizerError	The error object.
RankableAction	An action with it's associated features used for ranking.
RankedAction	A ranked action with its resulting probability.
RankRequest	Request a set of actions to be ranked by the Personalizer service.
RankResponse	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	PersonalizerError	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	InternalError	The error object.

PersonalizerError

The error object.

Name	Type	Description
code	ErrorCode	High level error code.
details	PersonalizerError[]	An array of details about specific errors that led to this reported error.
innerError	InternalError	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	RankableAction[]		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	RankedAction[]	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.