Language - Question Answering

The Language - Question Answering API is a cloud-based service that provides advanced natural language processing with state of the art transformer models to generate answers against custom question answering projects or raw text. Question answering is a feature in Language service which is enhanced from the QnA Maker service with additional features like support for unstructured documents and precise answering.

This connector is available in the following products and regions:

Service	Class	Regions
Logic Apps	Standard	All Logic Apps regions except the following:      -   Azure China regions
Power Automate	Premium	All Power Automate regions except the following:      -   China Cloud operated by 21Vianet
Power Apps	Premium	All Power Apps regions except the following:      -   China Cloud operated by 21Vianet

Contact
Name	Question Answering Support
URL	https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/overview
Email	qnamakersupport@microsoft.com

Connector Metadata
Publisher	Microsot
Website	https://azure.microsoft.com/en-us/services/cognitive-services/question-answering/#overview
Privacy policy	https://privacy.microsoft.com/en-us/privacystatement
Categories	AI;Website

Language - Question Answering Connector is a connector to integrate any Power app with our new Question Answering feature within Language service. With this connector, users can now connect to the new as well as enhanced features of Question Answering. There are actions in this connector which help users to

• Generate answers from project
• Get project metadata
• Generate answers from provided text over a period of time, we plan to roll out more actions to give more functionalities to our customers.

Prerequisites

Follow instructions here to create a Custom question answering project.

How to get credentials

1. After deploying your project, click on “Get Prediction URL”.
2. Get your Site URL from the hostname of Prediction URL and your Account key which would be the Ocp-Apim-Subscription-Key.
3. Create a connection using your Account Key and Site URL.

Get started with your connector

Use Connector in a flow

1. Go to Microsoft Power Automate , and click on Create and select “Instant Cloud flow”.
2. For testing this connector, you can click on “Manually trigger a flow” and click on Create.
3. Click on “New Step” and search “Language – Question Answering” and choose amongst the three actions.

Actions:

Generate Answer from Project

1. This action helps in answering the specified question using your knowledge base in your project.
2. You can give this query for generating answer from your “Sample-project”
3. Learn more about the request body from here: Question Answering - Get Answers - REST API (Azure Cognitive Services) | Microsoft Docs

Get Project Metadata

1. This action helps in getting all the metadata of your project.
2. Give your project name to get metadata of your project.

Generate answer from provided text

1. This action helps in answering the specified question using the provided text. To use only this action, Custom Question Answering need not be enabled on Language resource.
2. This action doesn’t require a Custom Question Answering Project. It only needs a Language resource. You can create a language resource and copy your endpoint and key from Azure portal, in Keys and Endpoint section, to Site URL and Account Key respectively.
3. Query “ how long it takes to charge surface? ” on the following 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 ”
4. Learn more about the request body from here: Question Answering - Get Answers From Text - REST API (Azure Cognitive Services) | Microsoft Docs

Response

Generate Answer from Project

It will return an answer from your “Sample-project” for the question “Accessibility”. To know more about the response object for this action, visit Question Answering - Get Answers - REST API (Azure Cognitive Services) | Microsoft Docs

Generate Answer from provided text

It will extract answer for your question from the given text. To know more about the response object, visit Question Answering - Get Answers From Text - REST API (Azure Cognitive Services) | Microsoft Docs .

Get Project Metadata

It gets the requested project’s metadata. To know more about the response object, visit Question Answering Projects - Get Project Details - REST API (Azure Cognitive Services) | Microsoft Docs .

Known issues and limitations

We have not found any, please reach out to us if you find any at qnamakersupport@microsoft.com

Common errors and remedies

Please refer to this documentation : https://docs.microsoft.com/en-us/rest/api/cognitiveservices/questionanswering/question-answering

FAQ

Please refer to this documentation : https://docs.microsoft.com/en-us/azure/cognitive-services/language-service/question-answering/overview

Creating a connection

The connector supports the following authentication types:

Api Key	ApiKey	All regions	Shareable
Azure AD Integrated	Use Azure Active Directory to access your Azure Blob Storage.	All regions	Not shareable
Default [DEPRECATED]	This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.	All regions	Not shareable

Api Key

Auth ID: keyBasedAuth

Applicable: All regions

ApiKey

This is shareable connection. If the power app is shared with another user, connection is shared as well. For more information, please see the Connectors overview for canvas apps - Power Apps | Microsoft Docs

Name	Type	Description	Required
Account Key	securestring	The endpoint key for your language resource to be copied from Azure portal	True
Site URL	string	Hostname of your language resource to be copied from Azure portal	True

Azure AD Integrated

Auth ID: tokenBasedAuth

Applicable: All regions

Use Azure Active Directory to access your Azure Blob Storage.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name	Type	Description	Required
Site URL	string	Hostname of your language resource to be copied from Azure portal	True

Default [DEPRECATED]

Applicable: All regions

This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name	Type	Description	Required
Account Key	securestring	The endpoint key for your language resource to be copied from Azure portal	True
Site URL	string	Hostname of your language resource to be copied from Azure portal	True

Throttling Limits

Name	Calls	Renewal Period
API calls per connection	100	60 seconds

Actions

Generate answer from Project	This action helps in answering the specified question using your knowledge base in your project.
Generate answer from provided text	This action helps in answering the specified question using the provided text.
Get Project Metadata	This action helps in getting all the metadata of your project.

Generate answer from Project

Operation ID:

GenerateAnswer

This action helps in answering the specified question using your knowledge base in your project.

Parameters

Name	Key	Required	Type	Description
Project Name	projectName	True	string	This is the Project name you want to use.
Question	question	True	string	User question to query against the project.
User ID	userId		string	Unique identifier for the user.
Top #	top		integer	Maximum number of answers to be returned for the question.
Confidence Threshold	confidenceScoreThreshold		float	Minimum threshold score for answers. Value ranges from 0 to 1.
Ranker type	rankerType		string	Type of ranker to be used.
QnA ID	qnaId		string	This is the exact QnA ID to fetch from project.
Previous QnA ID	previousQnaId		integer	Previous turn top answer result QnA ID.
Previous User Query	previousUserQuery		string	Previous user query.
key	key		string	Metadata Key from Metadata dictionary used in the QnA.
value	value		string	Metadata Value from Metadata dictionary used in the QnA.
Join Metadata with	logicalOperation		string	Set 'OR' or 'AND' for corresponding logical operation for metadata filters.
Source Filter	sourceFilter		string	Find QnAs that are associated with any of the given list of sources in project.
Join Filters with	logicalOperation		string	Logical operation used to join metadata filter with source filter.
Enable precise answer	enable		boolean	Enable or disable Answer Span prediction.
Confidence Threshold	confidenceScoreThreshold		float	Minimum threshold score required to include a precise answer, value ranges from 0 to 1.
Top #	topAnswersWithSpan		integer	Number of Top answers to be considered for precise answer prediction from 1 to 10.
Include Unstructured Sources	includeUnstructuredSources		boolean	Flag to enable query over unstructured sources.
Deployment Name	deploymentName	True	string	This is the specific deployment of the project you want to use.
API Version	api-version	True	string	This is the Client API version.

Returns

Represents List of Question Answers.

Body

AnswersResult

Generate answer from provided text

Operation ID:

GetAnswersFromText

This action helps in answering the specified question using the provided text.

Parameters

Name	Key	Required	Type	Description
Question	question	True	string	User question to query against the given text records.
id	id	True	string	Unique identifier for the text record.
text	text	True	string	Text contents of the record.
Language	language		string	Language of the text records. This is BCP-47 representation of a language.
String Index Type	stringIndexType		string	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.
API Version	api-version	True	string	This is the Client API version.

Returns

Represents the answer results.

Body

AnswersFromTextResult

Get Project Metadata

Operation ID:

GetProjectDetails

This action helps in getting all the metadata of your project.

Parameters

Name	Key	Required	Type	Description
Project Name	ProjectNamePathParameter	True	string	The name of the project to use.
API Version	api-version	True	string	This is the Client API version.

Returns

Represents the project.

Body

ProjectMetadata

Definitions

ProjectMetadata

Represents the project.

Name	Path	Type	Description
projectName	projectName	string	Name of the project.
description	description	string	Description of the project.
Language	language	Language	Language of the text records. This is BCP-47 representation of a language.
defaultAnswer	settings.defaultAnswer	string	Default Answer response when no good match is found in the Knowledgebase.
multilingualResource	multilingualResource	boolean	Resource enabled for multiple languages across projects or not.
createdDateTime	createdDateTime	date-time	Project creation date-time.
lastModifiedDateTime	lastModifiedDateTime	date-time	Represents the project last modified date-time.
lastDeployedDateTime	lastDeployedDateTime	date-time	Represents the project last deployment date-time.

Language

Language of the text records. This is BCP-47 representation of a language.

Language of the text records. This is BCP-47 representation of a language.

Language

string

AnswersResult

Represents List of Question Answers.

Name	Path	Type	Description
answers	answers	array of KnowledgeBaseAnswer	Represents Answer Result list.
isUserQuestionAmbiguous	isUserQuestionAmbiguous	boolean	Returns a boolean value if user's question was ambiguous.

KnowledgeBaseAnswer

Represents project answer.

Name	Path	Type	Description
questions	questions	array of string	List of questions associated with the answer.
answer	answer	string	Answer text.
Confidence Threshold	confidenceScore	float	Answer confidence score, value ranges from 0 to 1.
QnA ID	id	integer	ID of the QnA result.
source	source	string	Source of QnA result.
metadata	metadata	object	Metadata associated with the answer, useful to categorize or filter question answers.
dialog	dialog	KnowledgeBaseAnswerDialog	Dialog associated with Answer.
answerSpan	answerSpan	AnswerSpan	Answer span object of QnA.

KnowledgeBaseAnswerDialog

Dialog associated with Answer.

Name	Path	Type	Description
isContextOnly	isContextOnly	boolean	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	prompts	array of KnowledgeBaseAnswerPrompt	List of prompts associated with the answer.

KnowledgeBaseAnswerPrompt

Prompt for an answer.

Name	Path	Type	Description
displayOrder	displayOrder	integer	Index of the prompt - used in ordering of the prompts.
qnaId	qnaId	integer	QnA ID corresponding to the prompt.
displayText	displayText	string	Text displayed to represent a follow up question prompt.

AnswerSpan

Answer span object of QnA.

Name	Path	Type	Description
text	text	string	Predicted text of precise answer.
Confidence Threshold	confidenceScore	float	Predicted score of precise answer, value ranges from 0 to 1.
offset	offset	integer	The Precise answer offset from the start of answer.
length	length	integer	The length of the precise answer.

AnswersFromTextResult

Represents the answer results.

Name	Path	Type	Description
answers	answers	array of TextAnswer	Represents the answer results.

TextAnswer

Represents answer result.

Name	Path	Type	Description
answer	answer	string	Answer Text.
Confidence Threshold	confidenceScore	float	Answer confidence score, value ranges from 0 to 1.
id	id	string	Record ID.
answerSpan	answerSpan	AnswerSpan	Answer span object of QnA.
offset	offset	integer	The sentence offset from the start of the document.
length	length	integer	The length of the sentence.