Skip to content

Commit 8007e55

Browse files
jbobackjboback
committed
fix
1 parent 46010ea commit 8007e55

File tree

1 file changed

+196
-0
lines changed

1 file changed

+196
-0
lines changed

‎articles/cognitive-services/QnAMaker/includes/quickstart-rest.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: "Quickstart: Use cURL & REST to manage knowledge base - QnA Maker"
3+
description: This quickstart shows you how to create, publish, and query your knowledge base using the REST APIs.
4+
ms.date: 1/22/2021
5+
ms.topic: include
6+
ms.custom: ignite-fall-2021
7+
---
8+
9+
## Prerequisites
10+
11+
> [!NOTE]
12+
> This documentation does not apply to the latest release. To learn about using the REST API with the latest release consult the [question answering REST API quickstart](../../language-service/question-answering/quickstart/sdk.md?pivots=rest)
13+
14+
* The current version of [cURL](https://curl.haxx.se/). Several command-line switches are used in the quickstarts, which are noted in the [cURL documentation](https://curl.haxx.se/docs/manpage.html).
15+
* You must have a [QnA Maker resource](../how-to/set-up-qnamaker-service-azure.md?tabs=v1#create-a-new-qna-maker-service), to use the key and resource name. You entered the resource **Name** during resource creation, then the key was created for you. The resource name is used as the subdomain for your endpoint. To retrieve your key and resource name, select **Quickstart** for your resource in the Azure portal. The resource name is the first subdomain of the endpoint URL:
16+
17+
`https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0`
18+
19+
> [!CAUTION]
20+
> The following BASH examples use the `\` line continuation character. If you console or terminal uses a different line continuation character, use this character.
21+
22+
## Create a knowledge base
23+
24+
To create a knowledge base with the REST APIs and cURL, you need to have the following information:
25+
26+
|Information|cURL configuration|Purpose|
27+
|--|--|--|
28+
|QnA Maker resource name|URL|used to construct URL|
29+
|QnA Maker resource key|`-h` param for `Ocp-Apim-Subscription-Key` header|Authenticate to QnA Maker service|
30+
|JSON describing knowledge base|`-d` param|[Examples](/rest/api/cognitiveservices/qnamaker/knowledgebase/create#examples) of JSON|
31+
|Size of the JSON in bytes|`-h` param for `Content-Size` header||
32+
33+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key, and JSON values and size of JSON.
34+
35+
```bash
36+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
37+
-X POST \
38+
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
39+
-H "Content-Type:application/json" \
40+
-H "Content-Size:107" \
41+
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/cognitive-services/qnamaker/faqs"]}'
42+
```
43+
44+
The cURL response from QnA Maker includes the `operationId` , which is required to [get status of the operation](#get-status-of-operation).
45+
46+
```json
47+
{
48+
"operationState": "NotStarted",
49+
"createdTimestamp": "2020-02-27T04:11:22Z",
50+
"lastActionTimestamp": "2020-02-27T04:11:22Z",
51+
"userId": "9596077b3e0441eb93d5080d6a15c64b",
52+
"operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
53+
}
54+
```
55+
56+
## Get status of operation
57+
58+
When you create a knowledge base, because the operation is async, the response includes information to determine the status.
59+
60+
|Information|cURL configuration|Purpose|
61+
|--|--|--|
62+
|QnA Maker resource name|URL|used to construct URL|
63+
|Operation Id|URL route|`/operations/REPLACE-WITH-YOUR-OPERATION-ID`|
64+
|QnA Maker resource key|`-h` param for `Ocp-Apim-Subscription-Key` header|Authenticate to QnA Maker service|
65+
66+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key, and operation ID.
67+
68+
```bash
69+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
70+
-X GET \
71+
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
72+
```
73+
74+
The cURL response includes the status. If the operation state is succeeded, then the `resourceLocation` includes the knowledge base ID.
75+
76+
```json
77+
{
78+
"operationState": "Succeeded",
79+
"createdTimestamp": "2020-02-27T04:54:07Z",
80+
"lastActionTimestamp": "2020-02-27T04:54:19Z",
81+
"resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
82+
"userId": "f596077b3e0441eb93d5080d6a15c64b",
83+
"operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
84+
}
85+
```
86+
## Publish knowledge base
87+
88+
Before you query the knowledge base, you need to:
89+
* Publish knowledge base
90+
* Get the runtime endpoint key
91+
92+
This task publishes the knowledge base. Getting the runtime endpoint key is a [separate task](#get-published-knowledge-bases-runtime-endpoint-key).
93+
94+
|Information|cURL configuration|Purpose|
95+
|--|--|--|
96+
|QnA Maker resource name|URL|used to construct URL|
97+
|QnA Maker resource key|`-h` param for `Ocp-Apim-Subscription-Key` header|Authenticate to QnA Maker service|
98+
|Knowledge base Id|URL route|`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`|
99+
100+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key, and knowledge base ID.
101+
102+
```bash
103+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
104+
-v \
105+
-X POST \
106+
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
107+
--data-raw ''
108+
```
109+
110+
The response status is 204 with no results. Use the `-v` command-line parameter to see verbose output for the cURL command. This will include the HTTP status.
111+
112+
## Get published knowledge base's runtime endpoint key
113+
114+
Before you query the knowledge base, you need to:
115+
* Publish knowledge base
116+
* Get the runtime endpoint key
117+
118+
This task getS the runtime endpoint key. Publishing the knowledge base is a [separate task](#publish-knowledge-base).
119+
120+
The runtime endpoint key is the same key for all knowledge bases using the QnA Maker resource.
121+
122+
|Information|cURL configuration|Purpose|
123+
|--|--|--|
124+
|QnA Maker resource name|URL|used to construct URL|
125+
|QnA Maker resource key|`-h` param for `Ocp-Apim-Subscription-Key` header|Authenticate to QnA Maker service|
126+
127+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key.
128+
129+
```bash
130+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
131+
-X GET \
132+
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
133+
```
134+
135+
The cURL response includes the runtime endpoint keys. Use just one of the keys when querying to get an answer from the knowledge base.
136+
137+
```json
138+
{
139+
"primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
140+
"secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
141+
"installedVersion": "4.0.5",
142+
"lastStableVersion": "4.0.6"
143+
}
144+
```
145+
146+
## Query for answer from published knowledge base
147+
148+
Getting an answer from the knowledge is done from a separate runtime than managing the knowledge base. Because it is a separate runtime, you need to authenticate with a runtime key.
149+
150+
|Information|cURL configuration|Purpose|
151+
|--|--|--|
152+
|QnA Maker resource name|URL|used to construct URL|
153+
|QnA Maker runtime key|`-h` param for `Authorization` header|The key is part of a string that includes the word `Endpointkey `. Authenticate to QnA Maker service|
154+
|Knowledge base Id|URL route|`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`|
155+
|JSON describing query|`-d` param|[Request body parameters](/rest/api/cognitiveservices/qnamakerruntime/runtime/generateanswer#request-body) and [examples](/rest/api/cognitiveservices/qnamakerruntime/runtime/generateanswer#examples) of JSON|
156+
|Size of the JSON in bytes|`-h` param for `Content-Size` header||
157+
158+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key, and knowledge base ID.
159+
160+
```bash
161+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
162+
-X POST \
163+
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
164+
-H "Content-Type:application/json" \
165+
-H "Content-Size:159" \
166+
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true, "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'
167+
```
168+
169+
A successful response includes the top answer along with other information a client application, such as a chat bot, needs to display an answer to the user.
170+
171+
## Delete knowledge base
172+
173+
When you are done with the knowledge base, delete it.
174+
175+
|Information|cURL configuration|Purpose|
176+
|--|--|--|
177+
|QnA Maker resource name|URL|used to construct URL|
178+
|QnA Maker resource key|`-h` param for `Ocp-Apim-Subscription-Key` header|Authenticate to QnA Maker service|
179+
|Knowledge base Id|URL route|`/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID`|
180+
181+
The cURL command is executed from a BASH shell. Edit this command with your own resource name, resource key, and knowledge base ID.
182+
183+
```bash
184+
curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
185+
-X DELETE \
186+
-v \
187+
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"
188+
```
189+
190+
The response status is 204 with no results. Use the `-v` command-line parameter to see verbose output for the cURL command. This will include the HTTP status.
191+
192+
## Additional resources
193+
194+
* [Authoring](/rest/api/cognitiveservices/qnamaker4.0/knowledgebase) Reference documentation
195+
* [Runtime](/rest/api/cognitiveservices/qnamaker4.0/runtime) Reference documentation
196+
* [Sample BASH scripts using cURL](https://github.com/Azure-Samples/cognitive-services-quickstart-code/tree/master/curl/QnAMaker)

0 commit comments

Comments
 (0)