Microsoft Azure Rank API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Rank API
  description: Manages ranking operations.
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
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RankResponse'
        default:
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Successful Rank request:
          $ref: ./examples/Rank.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RankRequest'
        description: A Personalizer 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'
    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

            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'
        excludedActions:
          description: 'The set of action ids to exclude from ranking.

            Personalizer 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.

            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
    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'
    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: '#/components/schemas/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.

            This is the action your application should display, and for which to report the reward.

            This might not be the first found in ''ranking''.'
          maxLength: 256
          type: string
          readOnly: true
    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: '#/components/parameters/Endpoint'