|
| 1 | +--- |
| 2 | +title: "Quickstart: Create knowledge base - REST, C# - QnA Maker" |
| 3 | +description: This C# REST-based quickstart walks you through creating a sample QnA Maker knowledge base, programmatically, that will appear in your Azure Dashboard of your Cognitive Services API account. |
| 4 | +ms.date: 12/16/2019 |
| 5 | +ROBOTS: NOINDEX,NOFOLLOW |
| 6 | +ms.custom: RESTCURL2020FEB27 |
| 7 | +ms.topic: conceptual |
| 8 | +#Customer intent: As an API or REST developer new to the QnA Maker service, I want to programmatically create a knowledge base using C#. |
| 9 | +--- |
| 10 | + |
| 11 | +# Quickstart: Create a knowledge base in QnA Maker using C# with REST |
| 12 | + |
| 13 | +This quickstart walks you through programmatically creating and publishing a sample QnA Maker knowledge base. QnA Maker automatically extracts questions and answers from semi-structured content, like FAQs, from [data sources](../Concepts/knowledge-base.md). The model for the knowledge base is defined in the JSON sent in the body of the API request. |
| 14 | + |
| 15 | +This quickstart calls QnA Maker APIs: |
| 16 | +* [Create KB](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase/create) |
| 17 | +* [Get Operation Details](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/operations/getdetails) |
| 18 | + |
| 19 | +[Reference documentation](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) | [C# Sample](https://github.com/Azure-Samples/cognitive-services-qnamaker-csharp/blob/master/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs) |
| 20 | + |
| 21 | +[!INCLUDE [Custom subdomains notice](../../../../includes/cognitive-services-custom-subdomains-note.md)] |
| 22 | + |
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +* The current version of [.NET Core](https://dotnet.microsoft.com/download/dotnet-core). |
| 26 | +* You must have a [QnA Maker resource](../How-To/set-up-qnamaker-service-azure.md). To retrieve your key and endpoint (which includes the resource name), select **Quickstart** for your resource in the Azure portal. |
| 27 | + |
| 28 | +### Create a new C# application |
| 29 | + |
| 30 | +Create a new .NET Core application in your preferred editor or IDE. |
| 31 | + |
| 32 | +In a console window (such as cmd, PowerShell, or Bash), use the `dotnet new` command to create a new console app with the name `qna-maker-quickstart`. This command creates a simple "Hello World" C# project with a single source file: *Program.cs*. |
| 33 | + |
| 34 | +```dotnetcli |
| 35 | +dotnet new console -n qna-maker-quickstart |
| 36 | +``` |
| 37 | + |
| 38 | +Change your directory to the newly created app folder. You can build the application with: |
| 39 | + |
| 40 | +```dotnetcli |
| 41 | +dotnet build |
| 42 | +``` |
| 43 | + |
| 44 | +The build output should contain no warnings or errors. |
| 45 | + |
| 46 | +```console |
| 47 | +... |
| 48 | +Build succeeded. |
| 49 | + 0 Warning(s) |
| 50 | + 0 Error(s) |
| 51 | +... |
| 52 | +``` |
| 53 | + |
| 54 | +## Add the required dependencies |
| 55 | + |
| 56 | +At the top of Program.cs, replace the single using statement with the following lines to add necessary dependencies to the project: |
| 57 | + |
| 58 | +[!code-csharp[Add the required dependencies](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=1-11 "Add the required dependencies")] |
| 59 | + |
| 60 | +## Add the required constants |
| 61 | + |
| 62 | +At the top of the Program class, add the required constants to access QnA Maker. |
| 63 | + |
| 64 | +Set the following values in environment variables: |
| 65 | + |
| 66 | +* `QNA_MAKER_SUBSCRIPTION_KEY` - The **key** is a 32 character string and is available in the Azure portal, on the QnA Maker resource, on the Quickstart page. This is not the same as the prediction endpoint key. |
| 67 | +* `QNA_MAKER_ENDPOINT` - The **endpoint** is the URL for authoring, in the format of `https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com`. This is not the same URL used to query the prediction endpoint. |
| 68 | + |
| 69 | +[!code-csharp[Add the required constants](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=17-26 "Add the required constants")] |
| 70 | + |
| 71 | +## Add the KB definition |
| 72 | + |
| 73 | +After the constants, add the following KB definition: |
| 74 | + |
| 75 | +[!code-csharp[Add the required constants](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=28-58 "Add the knowledge base definition")] |
| 76 | + |
| 77 | +## Add supporting functions and structures |
| 78 | +Add the following code block inside the Program class: |
| 79 | + |
| 80 | +[!code-csharp[Add supporting functions and structures](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=60-99 "Add supporting functions and structures")] |
| 81 | + |
| 82 | +## Add a POST request to create KB |
| 83 | + |
| 84 | +The following code makes an HTTPS request to the QnA Maker API to create a KB and receives the response: |
| 85 | + |
| 86 | +[!code-csharp[Add PostCreateKB to request via POST](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=145-165 "Add PostCreateKB to request via POST")] |
| 87 | + |
| 88 | +[!code-csharp[Add a POST request to create KB](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=101-122 "Add a POST request to create KB")] |
| 89 | + |
| 90 | +This API call returns a JSON response that includes the operation ID. Use the operation ID to determine if the KB is successfully created. |
| 91 | + |
| 92 | +```JSON |
| 93 | +{ |
| 94 | + "operationState": "NotStarted", |
| 95 | + "createdTimestamp": "2018-09-26T05:19:01Z", |
| 96 | + "lastActionTimestamp": "2018-09-26T05:19:01Z", |
| 97 | + "userId": "XXX9549466094e1cb4fd063b646e1ad6", |
| 98 | + "operationId": "8dfb6a82-ae58-4bcb-95b7-d1239ae25681" |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +## Add GET request to determine creation status |
| 103 | + |
| 104 | +Check the status of the operation. |
| 105 | + |
| 106 | +[!code-csharp[Add GetStatus to request via GET](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=167-187 "Add GetStatus to request via GET")] |
| 107 | + |
| 108 | +[!code-csharp[Add GET request to determine creation status](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=124-143 "Add GET request to determine creation status")] |
| 109 | + |
| 110 | +This API call returns a JSON response that includes the operation status: |
| 111 | + |
| 112 | +```JSON |
| 113 | +{ |
| 114 | + "operationState": "NotStarted", |
| 115 | + "createdTimestamp": "2018-09-26T05:22:53Z", |
| 116 | + "lastActionTimestamp": "2018-09-26T05:22:53Z", |
| 117 | + "userId": "XXX9549466094e1cb4fd063b646e1ad6", |
| 118 | + "operationId": "177e12ff-5d04-4b73-b594-8575f9787963" |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +Repeat the call until success or failure: |
| 123 | + |
| 124 | +```JSON |
| 125 | +{ |
| 126 | + "operationState": "Succeeded", |
| 127 | + "createdTimestamp": "2018-09-26T05:22:53Z", |
| 128 | + "lastActionTimestamp": "2018-09-26T05:23:08Z", |
| 129 | + "resourceLocation": "/knowledgebases/XXX7892b-10cf-47e2-a3ae-e40683adb714", |
| 130 | + "userId": "XXX9549466094e1cb4fd063b646e1ad6", |
| 131 | + "operationId": "177e12ff-5d04-4b73-b594-8575f9787963" |
| 132 | +} |
| 133 | +``` |
| 134 | + |
| 135 | +## Add CreateKB method |
| 136 | + |
| 137 | +The following method creates the KB and repeats checks on the status. The _create_ **Operation ID** is returned in the POST response header field **Location**, then used as part of the route in the GET request. Because the KB creation may take some time, you need to repeat calls to check the status until the status is either successful or fails. When the operation succeeds, the KB ID is returned in **resourceLocation**. |
| 138 | + |
| 139 | +[!code-csharp[Add CreateKB method](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=189-254 "Add CreateKB method")] |
| 140 | + |
| 141 | +## Add the CreateKB method to Main |
| 142 | + |
| 143 | +Change the Main method to call the CreateKB method: |
| 144 | + |
| 145 | +[!code-csharp[Add CreateKB method](~/samples-qnamaker-csharp/documentation-samples/quickstarts/create-knowledge-base/QnaQuickstartCreateKnowledgebase/Program.cs?range=256-265 "Add CreateKB method")] |
| 146 | + |
| 147 | +## Build and run the program |
| 148 | + |
| 149 | +Build and run the program. It will automatically send the request to the QnA Maker API to create the KB, then it will poll for the results every 30 seconds. Each response is printed to the console window. |
| 150 | + |
| 151 | +Once your knowledge base is created, you can view it in your QnA Maker Portal, [My knowledge bases](https://www.qnamaker.ai/Home/MyServices) page. |
| 152 | + |
| 153 | + |
| 154 | +[!INCLUDE [Clean up files and KB](../../../../includes/cognitive-services-qnamaker-quickstart-cleanup-resources.md)] |
| 155 | + |
| 156 | +## Next steps |
| 157 | + |
| 158 | +> [!div class="nextstepaction"] |
| 159 | +> [QnA Maker (V4) REST API Reference](https://go.microsoft.com/fwlink/?linkid=2092179) |
0 commit comments