Question Answering - Get Answers From Text

Reference

Service:: Azure AI Services

API Version:: 2023-04-01

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

HTTP

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

Status code:: 200

{
  "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