Merge pull request #80799 from diberry/0627-qna-api

[Cogsvcs] QnA Maker - REST API ref generateAnswer

Author: GitHubber17

articles/cognitive-services/QnAMaker/How-To/metadata-generateanswer-usage.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: cognitive-services
 ms.subservice: qna-maker
 ms.topic: article
-ms.date: 06/17/2019
+ms.date: 06/27/2019
 ms.author: diberry
 ---
 
@@ -32,13 +32,13 @@ Each QnA entity has a unique and persistent ID. You can use the ID to make updat
 
 ## Get answer predictions with the GenerateAnswer API
 
-You use the GenerateAnswer API in your bot or application to query your knowledge base with a user question, to get the best match from the question and answer sets.
+You use the [GenerateAnswer API](https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/generateanswer) in your bot or application to query your knowledge base with a user question, to get the best match from the question and answer sets.
 
 <a name="generateanswer-endpoint"></a>
 
 ## Publish to get GenerateAnswer endpoint 
 
-After you publish your knowledge base, either from the [QnA Maker portal](https://www.qnamaker.ai), or by using the [API](https://go.microsoft.com/fwlink/?linkid=2092179), you can get the details of your GenerateAnswer endpoint.
+After you publish your knowledge base, either from the [QnA Maker portal](https://www.qnamaker.ai), or by using the [API](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase/publish), you can get the details of your GenerateAnswer endpoint.
 
 To get your endpoint details:
 1. Sign in to [https://www.qnamaker.ai](https://www.qnamaker.ai).
@@ -54,34 +54,21 @@ You can also get your endpoint details from the **Settings** tab of your knowled
 
 ## GenerateAnswer request configuration
 
-You call GenerateAnswer with an HTTP POST request. For sample code that shows how to call GenerateAnswer, see the [quickstarts](../quickstarts/csharp.md).
+You call GenerateAnswer with an HTTP POST request. For sample code that shows how to call GenerateAnswer, see the [quickstarts](../quickstarts/csharp.md). 
 
-The **request URL** has the following format: 
+The POST request uses:
+
+* Required [URI parameters](https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/train#uri-parameters)
+* Required [header property](https://docs.microsoft.com/azure/cognitive-services/qnamaker/quickstarts/get-answer-from-knowledge-base-nodejs#add-a-post-request-to-send-question-and-get-an-answer), `Authorization`, for security
+* Required [body properties](https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/train#feedbackrecorddto). 
+
+The GenerateAnswer URL has the following format: 
 
 ```
 https://{QnA-Maker-endpoint}/knowledgebases/{knowledge-base-ID}/generateAnswer
 ```
 
-|HTTP request property|Name|Type|Purpose|
-|--|--|--|--|
-|URL route parameter|Knowledge base ID|string|The GUID for your knowledge base.|
-|URL route parameter|QnAMaker endpoint host|string|The hostname of the endpoint deployed in your Azure subscription. This is available on the **Settings** page after you publish the knowledge base. |
-|Header|Content-Type|string|The media type of the body sent to the API. Default value is: ``|
-|Header|Authorization|string|Your endpoint key (EndpointKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).|
-|Post Body|JSON object|JSON|The question with settings.|
-
-
-The JSON body has several settings:
-
-|JSON body property|Required|Type|Purpose|
-|--|--|--|--|
-|`question`|required|string|A user question to be sent to your knowledge base.|
-|`top`|optional|integer|The number of ranked results to include in the output. The default value is 1.|
-|`userId`|optional|string|A unique ID to identify the user. This ID will be recorded in the chat logs.|
-|`scoreThreshold`|optional|integer|Only answers with confidence score above this threshold will be returned. The default value is 0.|
-|`isTest`|optional|Boolean|If set to true, returns results from `testkb` Search index instead of published index.|
-|`strictFilters`|optional|string|If specified, tells QnA Maker to return only answers that have the specified metadata. Use `none` to indicate response should have no metadata filters. |
-|`RankerType`|optional|string|If specified as `QuestionOnly`, tells QnA Maker to search questions only. If not specified, QnA Maker searches questions and answers.
+Remember to set the HTTP header property of `Authorization` with a value of the string `EndpointKey ` with a trailing space then the endpoint key found on the **Settings** page.
 
 An example JSON body looks like:
 
@@ -104,19 +91,7 @@ An example JSON body looks like:
 
 ## GenerateAnswer response properties
 
-A successful response returns a status of 200 and a JSON response. 
-
-|Answers property (sorted by score)|Purpose|
-|--|--|
-|score|A ranking score between 0 and 100.|
-|Id|A unique ID assigned to the answer.|
-|questions|The questions provided by the user.|
-|answer|The answer to the question.|
-|source|The name of the source from which the answer was extracted or saved in the knowledge base.|
-|metadata|The metadata associated with the answer.|
-|metadata.name|Metadata name. (string, max Length: 100, required)|
-|metadata.value|Metadata value. (string, max Length: 100, required)|
-
+The [response](https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/generateanswer#successful_query) is a JSON object including all the information you need to display the answer and the next turn in the conversation, if available.
 
 ```json
 {

articles/cognitive-services/QnAMaker/toc.yml

@@ -145,6 +145,13 @@
 - name: Reference
   items:
   - name: REST API Reference
+    items: 
+    - name: Authoring APIs
+      href: https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase
+    - name: GenerateAnswer API
+      href: https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/generateanswer
+    - name: Train API
+      href: https://docs.microsoft.com/rest/api/cognitiveservices/qnamakerruntime/runtime/train
     href: https://go.microsoft.com/fwlink/?linkid=2092179 
   - name: FAQ
     href: faqs.md