Delen via

Knowledgebase - Create

  • Reference
Service:
Azure AI Services
API Version:
v5.0-preview.2

Asynchronous operation to create a new knowledgebase.

POST {Endpoint}/qnamaker/v5.0-preview.2/knowledgebases/create

URI Parameters

Name In Required Type Description
Endpoint
 path True

string

Supported Cognitive Services endpoint (e.g., https://< qnamaker-resource-name >.api.cognitiveservices.azure.com).

Request Header

Name Required Type Description
Ocp-Apim-Subscription-Key True

string

Request Body

Name Required Type Description
name True

string

Friendly name for the knowledgebase.
defaultAnswer

string

Default answer sent to user if no good match is found in the KB.
defaultAnswerUsedForExtraction

string

Text string to be used as the answer in any Q-A which has no extracted answer from the document but has a hierarchy. Required when EnableHierarchicalExtraction field is set to True.
enableHierarchicalExtraction

boolean

Enable hierarchical extraction of Q-A from files and urls. Value to be considered False if this field is not present.
enableMultipleLanguages

boolean

Set to true to enable creating KBs in different languages for the same resource.
files

FileDTO[]

List of files from which to Extract Q-A.
language

string

Language of the knowledgebase. Please find the list of supported languages here.
qnaList

QnADTO[]

List of Q-A (QnADTO) to be added to the knowledgebase. Q-A Ids are assigned by the service and should be omitted.
urls

string[]

List of URLs to be used for extracting Q-A.

Responses

Name Type Description
202 Accepted

Operation

Details of the asynchronous operation.
Other Status Codes

ErrorResponse

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful query

Sample request

POST {Endpoint}/qnamaker/v5.0-preview.2/knowledgebases/create


{
  "name": "QnA Maker FAQ",
  "qnaList": [
    {
      "id": 0,
      "answer": "You can change the default message if you use the QnAMakerDialog. See this for details: https://docs.botframework.com/en-us/azure-bot-service/templates/qnamaker/#navtitle",
      "source": "Custom Editorial",
      "questions": [
        "How can I change the default message from QnA Maker?"
      ],
      "metadata": []
    },
    {
      "id": 0,
      "answer": "You can use our REST apis to create a KB. See here for details: https://docs.microsoft.com/en-us/rest/api/cognitiveservices/qnamaker/knowledgebase/create",
      "source": "Custom Editorial",
      "questions": [
        "How do I programmatically create a KB?"
      ],
      "metadata": [
        {
          "name": "category",
          "value": "api"
        }
      ],
      "context": {
        "isContextOnly": false,
        "prompts": [
          {
            "displayOrder": 1,
            "displayText": "Update KB",
            "qna": {
              "answer": "You can use our REST apis to update your KB. See here for details: https://docs.microsoft.com/en-us/rest/api/cognitiveservices/qnamaker/knowledgebase/update",
              "questions": [
                "How do I programmatically update my KB?"
              ],
              "metadata": [
                {
                  "name": "category",
                  "value": "api"
                }
              ],
              "context": {
                "isContextOnly": false,
                "prompts": [
                  {
                    "displayOrder": 1,
                    "displayText": "Refresh Endpoint Keys",
                    "qna": {
                      "answer": "You can use our REST apis to refresh endpoint keys. See here for details: https://docs.microsoft.com/en-us/rest/api/cognitiveservices/qnamaker/endpointkeys/refreshkeys",
                      "questions": [
                        "How do I programmatically refresh endpoint keys?"
                      ]
                    }
                  }
                ]
              }
            }
          }
        ]
      }
    }
  ],
  "urls": [
    "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs",
    "https://docs.microsoft.com/en-us/bot-framework/resources-bot-framework-faq"
  ],
  "files": [
    {
      "fileName": "SurfaceManual.pdf",
      "fileUri": "https://download.microsoft.com/download/2/9/B/29B20383-302C-4517-A006-B0186F04BE28/surface-pro-4-user-guide-EN.pdf"
    }
  ]
}

Sample response

Status code:
202 
{
  "operationState": "NotStarted",
  "createdTimestamp": "2018-03-19T07:38:46Z",
  "lastActionTimestamp": "2018-03-19T07:39:29Z",
  "userId": "86bb8390-56c0-42c2-9f81-3de161981191",
  "operationId": "03a4f4ce-30a6-4ec6-b436-02bcdf6153e1"
}

Definitions

Name Description
Context

Context associated with Qna to be updated.
CreateKbDTO

Post body schema for CreateKb operation.
Error

The error object. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
ErrorCodeType

One of a server-defined set of error codes.
ErrorResponse

Error response. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
FileDTO

DTO to hold details of uploaded files.
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.
MetadataDTO

Name - value pair of metadata.
Operation

Record to track long running operation.
OperationStateType

Operation state.
PromptDTO

Prompt for an answer.
Qna

QnADTO - Either QnaId or QnADTO needs to be present in a PromptDTO object
QnADTO

Q-A object.

Context

Object

Context associated with Qna to be updated.

Name Type Description
isContextOnly

boolean

To mark if a prompt is relevant only with a previous question or not. true - Do not include this QnA as search result for queries without context false - ignores context and includes this QnA in search result
promptsToAdd

PromptDTO[]

List of prompts to be added to the qna.
promptsToDelete

integer[]

List of prompts associated with qna to be deleted

CreateKbDTO

Object

Post body schema for CreateKb operation.

Name Type Description
defaultAnswer

string

Default answer sent to user if no good match is found in the KB.
defaultAnswerUsedForExtraction

string

Text string to be used as the answer in any Q-A which has no extracted answer from the document but has a hierarchy. Required when EnableHierarchicalExtraction field is set to True.
enableHierarchicalExtraction

boolean

Enable hierarchical extraction of Q-A from files and urls. Value to be considered False if this field is not present.
enableMultipleLanguages

boolean

Set to true to enable creating KBs in different languages for the same resource.
files

FileDTO[]

List of files from which to Extract Q-A.
language

string

Language of the knowledgebase. Please find the list of supported languages here.
name

string

Friendly name for the knowledgebase.
qnaList

QnADTO[]

List of Q-A (QnADTO) to be added to the knowledgebase. Q-A Ids are assigned by the service and should be omitted.
urls

string[]

List of URLs to be used for extracting Q-A.

Error

Object

The error object. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
code

ErrorCodeType

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.

ErrorCodeType

Enumeration

One of a server-defined set of error codes.

Value Description
BadArgument
EndpointKeysError
ExtractionFailure
Forbidden
KbNotFound
NotFound
OperationNotFound
QnaRuntimeError
QuotaExceeded
SKULimitExceeded
ServiceError
Unauthorized
Unspecified
ValidationFailure

ErrorResponse

Object

Error response. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name Type Description
error

Error

The error object.

FileDTO

Object

DTO to hold details of uploaded files.

Name Type Description
fileName

string

File name. Supported file types are ".tsv", ".pdf", ".txt", ".docx", ".xlsx".
fileUri

string

Public URI of the file.
isUnstructured

boolean

Optional Flag to specify if the given file is Unstructured.

InnerErrorModel

Object

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.

Name Type Description
code

string

A more specific error code than was provided by the containing error.
innerError

InnerErrorModel

An object containing more specific information than the current object about the error.

MetadataDTO

Object

Name - value pair of metadata.

Name Type Description
name

string

Metadata name.
value

string

Metadata value.

Operation

Object

Record to track long running operation.

Name Type Description
createdTimestamp

string

Timestamp when the operation was created.
errorResponse

ErrorResponse

Error details in case of failures.
lastActionTimestamp

string

Timestamp when the current state was entered.
operationId

string

Operation Id.
operationState

OperationStateType

Operation state.
resourceLocation

string

Relative URI to the target resource location for completed resources.
userId

string

User Id

OperationStateType

Enumeration

Operation state.

Value Description
Failed
NotStarted
Running
Succeeded

PromptDTO

Object

Prompt for an answer.

Name Type Description
displayOrder

integer

Index of the prompt - used in ordering of the prompts
displayText

string

Text displayed to represent a follow up question prompt
qna

Qna

QnADTO - Either QnaId or QnADTO needs to be present in a PromptDTO object
qnaId

integer

Qna id corresponding to the prompt - if QnaId is present, QnADTO object is ignored.

Qna

Object

QnADTO - Either QnaId or QnADTO needs to be present in a PromptDTO object

Name Type Description
answer

string

Answer text
context

Context

Context of a QnA
id

integer

Unique id for the Q-A.
lastUpdatedTimestamp

string

Timestamp when the QnA was last updated.
metadata

MetadataDTO[]

List of metadata associated with the answer.
questions

string[]

List of questions associated with the answer.
source

string

Source from which Q-A was indexed. eg. https://docs.microsoft.com/en-us/azure/cognitive-services/QnAMaker/FAQs

QnADTO

Object

Q-A object.

Name Type Description
answer

string

Answer text
context

Context

Context of a QnA
id

integer

Unique id for the Q-A.
lastUpdatedTimestamp

string

Timestamp when the QnA was last updated.
metadata

MetadataDTO[]

List of metadata associated with the answer.
questions

string[]

List of questions associated with the answer.
source

string

Source from which Q-A was indexed. eg. https://docs.microsoft.com/en-us/azure/cognitive-services/QnAMaker/FAQs