swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Rank API
  description: Manages ranking operations.
schemes:
- https
tags:
- name: Rank
  description: Manages ranking operations.
paths:
  /rank:
    post:
      tags:
      - Rank
      summary: Microsoft Azure Post Rank
      description: Submit a Personalizer rank request. Receives a context and a list of actions. Returns which of the provided actions should be used by your application, in rewardActionId.
      operationId: microsoftAzureRank
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: rankRequest
        in: body
        description: A Personalizer Rank request.
        required: true
        schema:
          $ref: '#/definitions/RankRequest'
      responses:
        '201':
          description: Success
          schema:
            $ref: '#/definitions/RankResponse'
        default:
          description: Invalid request.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-examples:
        Successful Rank request:
          $ref: ./examples/Rank.json
definitions:
  ErrorResponse:
    description: Used to return an error to the client
    required:
    - error
    type: object
    properties:
      error:
        $ref: '#/definitions/PersonalizerError'
  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: '#/definitions/InternalError'
  RankResponse:
    description: Returns which action to use as rewardActionId, and additional information about each action as a result of a Rank request.
    type: object
    properties:
      ranking:
        description: The calculated ranking for the current request.
        type: array
        items:
          $ref: '#/definitions/RankedAction'
        readOnly: true
      eventId:
        description: The eventId for the round trip from request to response.
        maxLength: 256
        type: string
        readOnly: true
      rewardActionId:
        description: "The action chosen by the Personalizer service.\r\nThis is the action your application should display, and for which to report the reward.\r\nThis might not be the first found in 'ranking'."
        maxLength: 256
        type: string
        readOnly: true
  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: '#/definitions/PersonalizerError'
      innerError:
        $ref: '#/definitions/InternalError'
  RankRequest:
    description: Request a set of actions to be ranked by the Personalizer service.
    required:
    - actions
    type: object
    properties:
      contextFeatures:
        description: "Features of the context used for Personalizer as a\r\ndictionary of dictionaries. This is determined by your application, and\r\ntypically includes features about the current user, their\r\ndevice, profile information, aggregated data about time and date, etc.\r\nFeatures should not include personally identifiable information (PII),\r\nunique UserIDs, or precise timestamps."
        type: array
        items:
          type: object
      actions:
        description: "The set of actions the Personalizer service can pick from.\r\nThe set should not contain more than 50 actions.\r\nThe order of the actions does not affect the rank result but the order\r\nshould match the sequence your application would have used to display them.\r\nThe first item in the array will be used as Baseline item in Offline Evaluations."
        type: array
        items:
          $ref: '#/definitions/RankableAction'
      excludedActions:
        description: "The set of action ids to exclude from ranking.\r\nPersonalizer will consider the first non-excluded item in the array as the Baseline action when performing Offline Evaluations."
        type: array
        items:
          type: string
      eventId:
        description: "Optionally pass an eventId that uniquely identifies this Rank event.\r\nIf null, the service generates a unique eventId. The eventId will be used for\r\nassociating this request with its reward, as well as seeding the pseudo-random\r\ngenerator 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\r\nPersonalizer will expect a Reward call, otherwise it will assign the default\r\nReward to the event. Send true if it is possible the user will not see the action specified in the rank results,\r\n(e.g. because the page is rendering later, or the Rank results may be overridden by code further downstream).\r\nYou must call the Activate Event API if the event output is shown to users, otherwise Rewards will be ignored."
        default: false
        type: boolean
  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
  RankedAction:
    description: A ranked action with its resulting probability.
    type: object
    properties:
      id:
        description: Id of the action
        maxLength: 256
        type: string
        readOnly: true
      probability:
        format: float
        description: Probability of the action
        maximum: 1
        minimum: 0
        type: number
        readOnly: true
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'