Question Answering - Get Answers From Text

Answers the specified question using the provided text in the body.

POST {Endpoint}/language/:query-text?api-version=2023-04-01

URI Parameters

Name In Required Type Description
Endpoint
path True

string

Supported Cognitive Services endpoint (e.g., https://.api.cognitiveservices.azure.com).

api-version
query True

string

Client API version.

Request Body

Name Required Type Description
question True

string

User question to query against the given text records.

records True

TextDocument[]

Text records to be searched for given question.

language

string

Language of the text records. This is BCP-47 representation of a language. For example, use "en" for English; "es" for Spanish etc. If not set, use "en" for English as default.

stringIndexType

StringIndexType

Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

Responses

Name Type Description
200 OK

AnswersFromTextResult

A successful response to get answers from input text.

Other Status Codes

ErrorResponse

Error response.

Security

AADToken

These are the Azure Active Directory OAuth2 Flows. When paired with Azure role-based access 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.

To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.

Notes

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

The Authorization URL is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. * The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs. * Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.

  • Currently, Azure Active Directory v1.0 or v2.0 supports Work, School, and Guests but does not support Personal accounts.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
https://cognitiveservices.azure.com/.default https://cognitiveservices.azure.com/.default

Ocp-Apim-Subscription-Key

A subscription key for a Language service resource.

Type: apiKey
In: header

Examples

Successful query

Sample request

POST {Endpoint}/language/:query-text?api-version=2023-04-01

{
  "question": "how long it takes to charge surface?",
  "records": [
    {
      "id": "1",
      "text": "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it."
    },
    {
      "id": "2",
      "text": "You can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface."
    }
  ],
  "language": "en"
}

Sample response

{
  "answers": [
    {
      "answer": "Power and charging. It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
      "confidenceScore": 0.93,
      "id": "1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0,
        "offset": 28,
        "length": 45
      },
      "offset": 0,
      "length": 224
    },
    {
      "answer": "It takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
      "confidenceScore": 0.92,
      "id": "1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0,
        "offset": 8,
        "length": 25
      },
      "offset": 20,
      "length": 224
    },
    {
      "answer": "It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
      "confidenceScore": 0.05,
      "id": "1",
      "answerSpan": null,
      "offset": 110,
      "length": 244
    }
  ]
}

Definitions

Name Description
AnswersFromTextOptions

The question and text record parameters to answer.

AnswersFromTextResult

Represents the answer results.

AnswerSpan

Answer span object of QnA.

Error

The error object.

ErrorCode

Human-readable error code.

ErrorResponse

Error response.

InnerErrorCode

Human-readable error code.

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

StringIndexType

Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

TextAnswer

Represents answer result.

TextDocument

Represent input text record to be queried.

AnswersFromTextOptions

The question and text record parameters to answer.

Name Type Default value Description
language

string

Language of the text records. This is BCP-47 representation of a language. For example, use "en" for English; "es" for Spanish etc. If not set, use "en" for English as default.

question

string

User question to query against the given text records.

records

TextDocument[]

Text records to be searched for given question.

stringIndexType

StringIndexType

TextElements_v8

Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

AnswersFromTextResult

Represents the answer results.

Name Type Description
answers

TextAnswer[]

Represents the answer results.

AnswerSpan

Answer span object of QnA.

Name Type Description
confidenceScore

number

Predicted score of answer span, value ranges from 0 to 1.

length

integer

The length of the answer span.

offset

integer

The answer span offset from the start of answer.

text

string

Predicted text of answer span.

Error

The error object.

Name Type Description
code

ErrorCode

One of a server-defined set of error codes.

details

Error[]

An array of details about specific errors that led to this reported error.

innererror

InnerErrorModel

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

message

string

A human-readable representation of the error.

target

string

The target of the error.

ErrorCode

Human-readable error code.

Name Type Description
AzureCognitiveSearchIndexLimitReached

string

AzureCognitiveSearchIndexNotFound

string

AzureCognitiveSearchNotFound

string

AzureCognitiveSearchThrottling

string

Conflict

string

Forbidden

string

InternalServerError

string

InvalidArgument

string

InvalidRequest

string

NotFound

string

OperationNotFound

string

ProjectNotFound

string

QuotaExceeded

string

ServiceUnavailable

string

Timeout

string

TooManyRequests

string

Unauthorized

string

Warning

string

ErrorResponse

Error response.

Name Type Description
error

Error

The error object.

InnerErrorCode

Human-readable error code.

Name Type Description
AzureCognitiveSearchNotFound

string

AzureCognitiveSearchThrottling

string

EmptyRequest

string

ExtractionFailure

string

InvalidCountryHint

string

InvalidDocument

string

InvalidDocumentBatch

string

InvalidParameterValue

string

InvalidRequest

string

InvalidRequestBodyFormat

string

KnowledgeBaseNotFound

string

MissingInputDocuments

string

ModelVersionIncorrect

string

UnsupportedLanguageCode

string

InnerErrorModel

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

InnerErrorCode

One of a server-defined set of error codes.

details

object

Error details.

innererror

InnerErrorModel

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

message

string

Error message.

target

string

Error target.

StringIndexType

Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.

Name Type Description
TextElements_v8

string

Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo.

UnicodeCodePoint

string

Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python.

Utf16CodeUnit

string

Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript.

TextAnswer

Represents answer result.

Name Type Description
answer

string

Answer.

answerSpan

AnswerSpan

Answer span object with respect to user's question.

confidenceScore

number

answer confidence score, value ranges from 0 to 1.

id

string

record ID.

length

integer

The length of the sentence.

offset

integer

The sentence offset from the start of the document.

TextDocument

Represent input text record to be queried.

Name Type Description
id

string

Unique identifier for the text record.

text

string

Text contents of the record.