Multi Slot - Rank

Service:: Azure AI Services

API Version:: v1.1-preview.1

Post multi-slot Rank.
Submit a Personalizer multi-slot rank request. Receives a context, a list of actions, and a list of slots. Returns which of the provided actions should be used in each slot, in each rewardActionId.

POST {Endpoint}/personalizer/v1.1-preview.1/multislot/rank

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoint.

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. The first item in the array will be used as Baseline item in Offline Evaluations.
slots	True	SlotRequest[]	The set of slots the Personalizer service should select actions for. The set should not contain more than 50 slots.
contextFeatures		object[]	Features of the context used for Personalizer as a dictionary of dictionaries. This is determined by your application, and typically includes features about the current user, their device, profile information, aggregated data about time and date, etc. Features should not include personally identifiable information (PII), unique UserIDs, or precise timestamps.
deferActivation		boolean	Send false if it is certain the rewardActionId in rank results will be shown to the user, 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 action specified in the rank results, (e.g. because the page is rendering later, or the Rank results may be overridden by code further downstream). You must call the Activate Event API if the event output is shown to users, otherwise Rewards will be ignored.
eventId		string maxLength: 256	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.

Responses

Name	Type	Description
201 Created	MultiSlotRankResponse	Success
Other Status Codes	ErrorResponse	Invalid request.

Examples

Successful MultiSlot_Rank request

Sample request

HTTP

POST {Endpoint}/personalizer/v1.1-preview.1/multislot/rank

{
  "contextFeatures": [
    {
      "user": {
        "profileType": "AnonymousUser",
        "latLong": "47.6,-122.1"
      }
    },
    {
      "environment": {
        "dayOfMonth": "28",
        "monthOfYear": "8",
        "weather": "Sunny"
      }
    },
    {
      "device": {
        "mobile": true,
        "windows": true
      }
    },
    {
      "recentActivity": {
        "itemsInCart": 3
      }
    }
  ],
  "actions": [
    {
      "id": "NewsArticle",
      "features": [
        {
          "type": "News"
        }
      ]
    },
    {
      "id": "SportsArticle",
      "features": [
        {
          "type": "Sports"
        }
      ]
    },
    {
      "id": "EntertainmentArticle",
      "features": [
        {
          "type": "Entertainment"
        }
      ]
    }
  ],
  "slots": [
    {
      "id": "Main Article",
      "features": [
        {
          "size": "Large",
          "position": "Top Middle"
        }
      ],
      "excludedActions": [
        "SportsArticle"
      ],
      "baselineAction": "EntertainmentArticle"
    },
    {
      "id": "Side Bar",
      "features": [
        {
          "size": "Small"
        }
      ],
      "baselineAction": "NewsArticle"
    }
  ],
  "eventId": "75269AD0-BFEE-4598-8196-C57383D38E10",
  "deferActivation": false
}

Sample response

Status code:: 201

{
  "slots": [
    {
      "id": "Main Article",
      "rewardActionId": "EntertainmentArticle"
    },
    {
      "id": "Side Bar",
      "rewardActionId": "SportsArticle"
    }
  ],
  "eventId": "75269AD0-BFEE-4598-8196-C57383D38E10"
}

Definitions

Name	Description
ErrorResponse	Used to return an error to the client
InternalError	An object containing more specific information than the parent object about the error.
MultiSlotRankRequest
MultiSlotRankResponse
PersonalizerError	The error object.
PersonalizerErrorCode	Error Codes returned by Personalizer
RankableAction	An action with its associated features used for ranking.
SlotRequest	A slot with it's associated features and list of excluded actions
SlotResponse

ErrorResponse

Object

Used to return an error to the client

Name	Type	Description
error	PersonalizerError	The error object.

InternalError

Object

An object containing more specific information than the parent object about the error.

Name	Type	Description
code	string	Detailed error code.
innererror	InternalError	An object containing more specific information than the parent object about the error.

MultiSlotRankRequest

Object

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. The first item in the array will be used as Baseline item in Offline Evaluations.
contextFeatures	object[]		Features of the context used for Personalizer as a dictionary of dictionaries. This is determined by your application, and typically includes features about the current user, their device, profile information, aggregated data about time and date, etc. Features should not include personally identifiable information (PII), unique UserIDs, or precise timestamps.
deferActivation	boolean	False	Send false if it is certain the rewardActionId in rank results will be shown to the user, 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 action specified in the rank results, (e.g. because the page is rendering later, or the Rank results may be overridden by code further downstream). You must call the Activate Event API if the event output is shown to users, otherwise Rewards will be ignored.
eventId	string maxLength: 256		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.
slots	SlotRequest[]		The set of slots the Personalizer service should select actions for. The set should not contain more than 50 slots.

MultiSlotRankResponse

Object

Name	Type	Description
eventId	string maxLength: 256	The eventId for the round trip from request to response.
slots	SlotResponse[]	Each slot has a corresponding rewardActionID which is the action ID recommended by Personalizer.

PersonalizerError

Object

The error object.

Name	Type	Description
code	PersonalizerErrorCode	Error Codes returned by Personalizer
details	PersonalizerError[]	An array of details about specific errors that led to this reported error.
innerError	InternalError	An object containing more specific information than the parent object about the error.
message	string	A message explaining the error reported by the service.
target	string	Error source element.

PersonalizerErrorCode

Enumeration

Error Codes returned by Personalizer

Value	Description
BadRequest	Request could not be understood by the server.
InvalidServiceConfiguration	Invalid service configuration.
InvalidLearningModeServiceConfiguration	Updating defaultReward, rewardWaitTime and rewardAggregation when changing learning mode from Online to Apprentice mode and vice versa is not allowed. Make the mode change and then change the additional settings with an additional API call.
InvalidPolicyConfiguration	Invalid policy configuration.
InvalidPolicyContract	Invalid policy contract.
InvalidEvaluationContract	Invalid evaluation contract.
DuplicateCustomPolicyNames	Custom policy names should be unique.
NoLogsExistInDateRange	No logs exist in date range.
LogsSizeExceedAllowedLimit	Total size of logs exceed allowed limit.
InvalidRewardRequest	Invalid reward request.
InvalidEventIdToActivate	Invalid activate event request.
InvalidRankRequest	Invalid request.
InvalidExportLogsRequest	Invalid request.
InvalidContainer	SAS Uri must be the Uri to a container that has write permissions.
InvalidModelMetadata	Invalid model metadata.
ApprenticeModeNeverTurnedOn	Apprentice mode never turned on.
MissingAppId	AppId is missing in the header.
InvalidRewardWaitTime	Reward wait time should be between 5 seconds and 2 days
InvalidMultiSlotApiAccess	Multi-slot feature is currently disabled. Please follow multi-slot Personalizer documentation to update your loop settings to enable multi-slot functionality.
ModelFileAccessDenied	Key vault Key used for customer managed key cannot be accessed.
ProblemTypeIncompatibleWithAutoOptimization	Auto-optimization is not compatible with multi-slot personalization.
ResourceNotFound	Requested resource does not exist on the server.
FrontEndNotFound	Front end not found.
EvaluationNotFound	Offline Evaluation not found.
LearningSettingsNotFound	Learning Settings not found in evaluation.
EvaluationModelNotFound	Model not found in evaluation.
LogsPropertiesNotFound	Log properties not found.
ModelRankingError	Error while ranking actions using model. Please verify the learning settings are valid.
InternalServerError	A generic error has occurred on the server.
RankNullResponse	Rank call returned null response.
UpdateConfigurationFailed	Failed to update configuration.
ModelResetFailed	Model reset failed.
ModelPublishFailed	Model publish failed.
ModelMetadataUpdateFailed	Model metadata update failed.
OperationNotAllowed	This operation is not allowed at this time.

RankableAction

Object

An action with its associated features used for ranking.

Name	Type	Description
features	object[]	List of dictionaries containing features.
id	string maxLength: 256	Id of the action.

SlotRequest

Object

A slot with it's associated features and list of excluded actions

Name	Type	Description
baselineAction	string	The 'baseline action' ID for the slot. The BaselineAction is the Id of the Action your application would use in that slot if Personalizer didn't exist. BaselineAction must be defined for every slot. BaselineAction should never be part of ExcludedActions. Each slot must have a unique BaselineAction which corresponds to an an action from the event's Actions list.
excludedActions	string[]	List of excluded action Ids.
features	object[]	List of dictionaries containing slot features.
id	string	Slot ID

SlotResponse

Object

Name	Type	Description
id	string maxLength: 256	Id is the slot ID.
rewardActionId	string maxLength: 256	RewardActionID is the action ID recommended by Personalizer.

Share via

Multi Slot - Rank

URI Parameters

Request Body

Responses

Examples

Successful MultiSlot_Rank request

Sample request

Sample response

Definitions

ErrorResponse

InternalError

MultiSlotRankRequest

MultiSlotRankResponse

PersonalizerError

PersonalizerErrorCode

RankableAction

SlotRequest

SlotResponse