Microsoft Azure :Query Knowledgebases API

openapi: 3.2.0
info:
  title: Microsoft Azure Microsoft Cognitive Language Service…
  description: The language service API is a suite of natural language processing (NLP) skills built with best-in-class Microsoft machine learning algorithms. The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language detection and question answering. Further documentation can be found in https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview.
  version: 2023-04-15-preview
security:
- AADToken:
  - https://cognitiveservices.azure.com/.default
- apim_key: []
tags:
- name: :Query Knowledgebases
paths:
  /:query-knowledgebases:
    post:
      summary: Microsoft Azure Answers The Specified Question Using Your Knowledge Base
      operationId: microsoftAzureQuestionansweringGetanswers
      parameters:
      - $ref: '#/components/parameters/AnswersOptions'
      - $ref: common.json#/parameters/ProjectNameQueryParameter
      - $ref: common.json#/parameters/DeploymentNameQueryParameter
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: A successful response to get answers from knowledge base.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswersResult'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful query:
          $ref: ./examples/questionanswering/SuccessfulQueryKnowledgebases.json
      description: Needs a more full description created.
      tags:
      - :Query Knowledgebases
components:
  schemas:
    MetadataRecord:
      type: object
      description: Object to provide the key value pair for each metadata.
      additionalProperties: false
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: Metadata Key from Metadata dictionary used in the QnA.
        value:
          type: string
          description: Metadata Value from Metadata dictionary used in the QnA.
    KnowledgeBaseAnswerPrompt:
      type: object
      description: Prompt for an answer.
      properties:
        displayOrder:
          type: integer
          description: Index of the prompt - used in ordering of the prompts.
          format: int32
        qnaId:
          type: integer
          description: QnA ID corresponding to the prompt.
          format: int32
        displayText:
          type: string
          description: Text displayed to represent a follow up question prompt.
          maxLength: 200
    KnowledgeBaseAnswerContext:
      type: object
      description: Context object with previous QnA's information.
      additionalProperties: false
      required:
      - previousQnaId
      properties:
        previousQnaId:
          type: integer
          description: Previous turn top answer result QnA ID.
          format: int32
        previousUserQuery:
          type: string
          x-ms-client-name: previousQuestion
          description: Previous user query.
    AnswersOptions:
      type: object
      description: Parameters to query a knowledge base.
      additionalProperties: false
      properties:
        qnaId:
          type: integer
          description: Exact QnA ID to fetch from the knowledge base, this field takes priority over question.
          format: int32
        question:
          type: string
          description: User question to query against the knowledge base.
        top:
          type: integer
          description: Max number of answers to be returned for the question.
          format: int32
        userId:
          type: string
          description: Unique identifier for the user.
        confidenceScoreThreshold:
          type: number
          format: double
          x-ms-client-name: confidenceThreshold
          description: Minimum threshold score for answers, value ranges from 0 to 1.
          maximum: 1
          minimum: 0
        context:
          x-ms-client-name: answerContext
          description: Context object with previous QnA's information.
          $ref: '#/components/schemas/KnowledgeBaseAnswerContext'
        rankerType:
          type: string
          x-ms-client-name: rankerKind
          description: Type of ranker to be used.
          x-ms-enum:
            name: RankerKind
            modelAsString: true
            values:
            - value: QuestionOnly
              description: Question only ranker.
            - value: Default
              description: Default ranker.
          enum:
          - Default
          - QuestionOnly
        filters:
          description: Filter QnAs based on given metadata list and knowledge base sources.
          $ref: '#/components/schemas/QueryFilters'
        answerSpanRequest:
          x-ms-client-name: shortAnswerOptions
          description: To configure Answer span prediction feature.
          $ref: '#/components/schemas/ShortAnswerOptions'
        includeUnstructuredSources:
          type: boolean
          description: (Optional) Flag to enable Query over Unstructured Sources.
    QueryFilters:
      type: object
      description: filters over knowledge base.
      additionalProperties: false
      properties:
        metadataFilter:
          type: object
          $ref: '#/components/schemas/MetadataFilter'
        sourceFilter:
          type: object
          $ref: '#/components/schemas/SourceFilter'
        logicalOperation:
          type: string
          description: Logical operation used to join metadata filter with source filter.
          $ref: '#/components/schemas/LogicalOperationKind'
          default: AND
    SourceFilter:
      type: array
      description: Find QnAs that are associated with any of the given list of sources in knowledge base.
      items:
        type: string
    KnowledgeBaseAnswerDialog:
      type: object
      description: Dialog associated with Answer.
      properties:
        isContextOnly:
          type: boolean
          description: To mark if a prompt is relevant only with a previous question or not. If true, do not include this QnA as search result for queries without context; otherwise, if false, ignores context and includes this QnA in search result.
        prompts:
          type: array
          description: List of prompts associated with the answer.
          maxItems: 20
          items:
            $ref: '#/components/schemas/KnowledgeBaseAnswerPrompt'
    MetadataFilter:
      type: object
      description: Find QnAs that are associated with the given list of metadata.
      additionalProperties: false
      properties:
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/MetadataRecord'
        logicalOperation:
          type: string
          description: Operation used to join metadata filters.
          $ref: '#/components/schemas/LogicalOperationKind'
          default: AND
    LogicalOperationKind:
      type: string
      description: Set to 'OR' or 'AND' for using corresponding logical operation.
      x-ms-enum:
        name: LogicalOperationKind
        modelAsString: true
      enum:
      - AND
      - OR
    KnowledgeBaseAnswer:
      type: object
      description: Represents knowledge base answer.
      additionalProperties: false
      properties:
        questions:
          type: array
          description: List of questions associated with the answer.
          items:
            type: string
        answer:
          type: string
          description: Answer text.
        confidenceScore:
          type: number
          format: double
          x-ms-client-name: confidence
          description: Answer confidence score, value ranges from 0 to 1.
          maximum: 1
          minimum: 0
        id:
          type: integer
          x-ms-client-name: qnaId
          description: ID of the QnA result.
          format: int32
        source:
          type: string
          description: Source of QnA result.
        metadata:
          type: object
          description: Metadata associated with the answer, useful to categorize or filter question answers.
          additionalProperties:
            type: string
        dialog:
          type: object
          $ref: '#/components/schemas/KnowledgeBaseAnswerDialog'
        answerSpan:
          type: object
          x-ms-client-name: shortAnswer
          description: Answer span object of QnA with respect to user's question.
          $ref: '#/components/schemas/AnswerSpan'
    AnswersResult:
      type: object
      description: Represents List of Question Answers.
      additionalProperties: false
      properties:
        answers:
          type: array
          description: Represents Answer Result list.
          items:
            $ref: '#/components/schemas/KnowledgeBaseAnswer'
    AnswerSpan:
      type: object
      description: Answer span object of QnA.
      additionalProperties: false
      properties:
        text:
          type: string
          description: Predicted text of answer span.
        confidenceScore:
          type: number
          x-ms-client-name: confidence
          description: Predicted score of answer span, value ranges from 0 to 1.
          format: double
          maximum: 1
          minimum: 0
        offset:
          type: integer
          description: The answer span offset from the start of answer.
          format: int32
        length:
          type: integer
          description: The length of the answer span.
          format: int32
    ShortAnswerOptions:
      type: object
      description: To configure Answer span prediction feature.
      additionalProperties: false
      required:
      - enable
      properties:
        enable:
          type: boolean
          description: Enable or disable Answer Span prediction.
          enum:
          - true
          x-ms-enum:
            name: enable
            modelAsString: false
        confidenceScoreThreshold:
          type: number
          format: double
          x-ms-client-name: confidenceThreshold
          description: Minimum threshold score required to include an answer span, value ranges from 0 to 1.
          maximum: 1
          minimum: 0
        topAnswersWithSpan:
          type: integer
          x-ms-client-name: top
          description: Number of Top answers to be considered for span prediction from 1 to 10.
          format: int32
          maximum: 10
          minimum: 1
  parameters:
    AnswersOptions:
      name: knowledgeBaseQueryOptions
      in: body
      required: true
      schema:
        $ref: '#/components/schemas/AnswersOptions'
      description: Post body of the request.
      x-ms-parameter-location: method
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://cognitiveservices.azure.com/.default: https://cognitiveservices.azure.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a  built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts."
    apim_key:
      type: apiKey
      description: A subscription key for a Language service resource.
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/language'
  useSchemePrefix: false
  parameters:
  - $ref: common.json#/parameters/Endpoint