Microsoft Azure MultiSlotRank API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Multi Slot Rank API
  description: Manages multi-slot ranking operations.
tags:
- name: MultiSlotRank
  description: Manages multi-slot ranking operations.
paths:
  /multislot/rank:
    post:
      tags:
      - MultiSlotRank
      summary: Microsoft Azure Post Multi Slot Rank
      description: 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.
      operationId: microsoftAzureMultislotRank
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSlotRankResponse'
        default:
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Successful MultiSlot_Rank request:
          $ref: ./examples/MultiSlot_Rank.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiSlotRankRequest'
        description: A Personalizer multi-slot Rank request.
        required: true
components:
  schemas:
    ErrorResponse:
      description: Used to return an error to the client
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/PersonalizerError'
    RankableAction:
      description: An action with its associated features used for ranking.
      required:
      - id
      - features
      type: object
      properties:
        id:
          description: Id of the action.
          maxLength: 256
          type: string
        features:
          description: List of dictionaries containing features.
          type: array
          items:
            type: object
    PersonalizerError:
      description: The error object.
      required:
      - code
      - message
      type: object
      properties:
        code:
          description: Error Codes returned by Personalizer
          enum:
          - BadRequest
          - InvalidServiceConfiguration
          - InvalidLearningModeServiceConfiguration
          - InvalidPolicyConfiguration
          - InvalidPolicyContract
          - InvalidEvaluationContract
          - DuplicateCustomPolicyNames
          - NoLogsExistInDateRange
          - LogsSizeExceedAllowedLimit
          - InvalidRewardRequest
          - InvalidEventIdToActivate
          - InvalidRankRequest
          - InvalidExportLogsRequest
          - InvalidRequest
          - InvalidContainer
          - InvalidModelMetadata
          - ApprenticeModeNeverTurnedOn
          - MissingAppId
          - InvalidRewardWaitTime
          - InvalidMultiSlotApiAccess
          - ModelFileAccessDenied
          - ProblemTypeIncompatibleWithAutoOptimization
          - ResourceNotFound
          - FrontEndNotFound
          - EvaluationNotFound
          - LearningSettingsNotFound
          - EvaluationModelNotFound
          - LogsPropertiesNotFound
          - ModelRankingError
          - InternalServerError
          - RankNullResponse
          - UpdateConfigurationFailed
          - ModelResetFailed
          - ModelPublishFailed
          - ModelMetadataUpdateFailed
          - OperationNotAllowed
          type: string
          x-ms-enum:
            name: PersonalizerErrorCode
            modelAsString: true
            values:
            - value: BadRequest
              description: Request could not be understood by the server.
            - value: InvalidServiceConfiguration
              description: Invalid service configuration.
            - value: InvalidLearningModeServiceConfiguration
              description: 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.
            - value: InvalidPolicyConfiguration
              description: Invalid policy configuration.
            - value: InvalidPolicyContract
              description: Invalid policy contract.
            - value: InvalidEvaluationContract
              description: Invalid evaluation contract.
            - value: DuplicateCustomPolicyNames
              description: Custom policy names should be unique.
            - value: NoLogsExistInDateRange
              description: No logs exist in date range.
            - value: LogsSizeExceedAllowedLimit
              description: Total size of logs exceed allowed limit.
            - value: InvalidRewardRequest
              description: Invalid reward request.
            - value: InvalidEventIdToActivate
              description: Invalid activate event request.
            - value: InvalidRankRequest
              description: Invalid request.
            - value: InvalidExportLogsRequest
              description: Invalid request.
            - value: InvalidRequest
              description: Invalid request.
            - value: InvalidContainer
              description: SAS Uri must be the Uri to a container that has write permissions.
            - value: InvalidModelMetadata
              description: Invalid model metadata.
            - value: ApprenticeModeNeverTurnedOn
              description: Apprentice mode never turned on.
            - value: MissingAppId
              description: AppId is missing in the header.
            - value: InvalidRewardWaitTime
              description: Reward wait time should be between 5 seconds and 2 days
            - value: InvalidMultiSlotApiAccess
              description: Multi-slot feature is currently disabled. Please follow multi-slot Personalizer documentation to update your loop settings to enable multi-slot functionality.
            - value: ModelFileAccessDenied
              description: Key vault Key used for customer managed key cannot be accessed.
            - value: ProblemTypeIncompatibleWithAutoOptimization
              description: Auto-optimization is not compatible with multi-slot personalization.
            - value: ResourceNotFound
              description: Requested resource does not exist on the server.
            - value: FrontEndNotFound
              description: Front end not found.
            - value: EvaluationNotFound
              description: Offline Evaluation not found.
            - value: LearningSettingsNotFound
              description: Learning Settings not found in evaluation.
            - value: EvaluationModelNotFound
              description: Model not found in evaluation.
            - value: LogsPropertiesNotFound
              description: Log properties not found.
            - value: ModelRankingError
              description: Error while ranking actions using model. Please verify the learning settings are valid.
            - value: InternalServerError
              description: A generic error has occurred on the server.
            - value: RankNullResponse
              description: Rank call returned null response.
            - value: UpdateConfigurationFailed
              description: Failed to update configuration.
            - value: ModelResetFailed
              description: Model reset failed.
            - value: ModelPublishFailed
              description: Model publish failed.
            - value: ModelMetadataUpdateFailed
              description: Model metadata update failed.
            - value: OperationNotAllowed
              description: This operation is not allowed at this time.
        message:
          description: A message explaining the error reported by the service.
          type: string
        target:
          description: Error source element.
          type: string
        details:
          description: An array of details about specific errors that led to this reported error.
          type: array
          items:
            $ref: '#/components/schemas/PersonalizerError'
        innerError:
          $ref: '#/components/schemas/InternalError'
    SlotRequest:
      description: A slot with it's associated features and list of excluded actions
      required:
      - baselineAction
      - id
      type: object
      properties:
        id:
          description: Slot ID
          type: string
        features:
          description: List of dictionaries containing slot features.
          type: array
          items:
            type: object
        excludedActions:
          description: List of excluded action Ids.
          type: array
          items:
            type: string
        baselineAction:
          description: '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.'
          type: string
    InternalError:
      description: An object containing more specific information than the parent object about the error.
      type: object
      properties:
        code:
          description: Detailed error code.
          type: string
        innererror:
          $ref: '#/components/schemas/InternalError'
    MultiSlotRankRequest:
      required:
      - actions
      - slots
      type: object
      properties:
        contextFeatures:
          description: '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.'
          type: array
          items:
            type: object
        actions:
          description: '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.'
          type: array
          items:
            $ref: '#/components/schemas/RankableAction'
        slots:
          description: 'The set of slots the Personalizer service should select actions for.

            The set should not contain more than 50 slots.'
          type: array
          items:
            $ref: '#/components/schemas/SlotRequest'
        eventId:
          description: '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.'
          maxLength: 256
          type: string
        deferActivation:
          description: '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.'
          default: false
          type: boolean
    SlotResponse:
      required:
      - id
      type: object
      properties:
        id:
          description: Id is the slot ID.
          maxLength: 256
          type: string
        rewardActionId:
          description: RewardActionID is the action ID recommended by Personalizer.
          maxLength: 256
          type: string
          readOnly: true
    MultiSlotRankResponse:
      type: object
      properties:
        slots:
          description: Each slot has a corresponding rewardActionID which is the action ID recommended by Personalizer.
          type: array
          items:
            $ref: '#/components/schemas/SlotResponse'
          readOnly: true
        eventId:
          description: The eventId for the round trip from request to response.
          maxLength: 256
          type: string
          readOnly: true
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'