密级	公开
版本	10D.2

AICP NLU 资源管理开发手册

4. 接口描述#

租户资源管理接口主要用于维护某个租户的所有NLU相关资源。

以下描述中，URI 前面都省略了 /v10/nlu/resource/{property}。

4.1 词典#

接口说明	接口	备注
查看系统词典	`GET /sys_lexicons`
查看租户词典	`GET /lexicons`
创建词典	`POST /lexicons`	返回`lexiconId`
查看词典	`GET /lexicons/<lexiconId>`
查看词典的所有词条	`GET /lexicons/<lexiconId>/words`
修改词典	`PATCH /lexicons/<lexiconId>`
删除词典	`DELETE /lexicons/<lexiconId>`
创建动态类别	`POST /lexicons/<lexiconId>/dynamic_classes`	返回`dynamicId`
查看动态类别	`GET /lexicons/<lexiconId>/dynamic_classes/<dynamicId>`
修改动态类别	`PATCH /lexicons/<lexiconId>/dynamic_classes/<dynamicId>`
删除动态类别	`DELETE /lexicons/<lexiconId>/dynamic_classes/<dynamicId>`
创建词条	`POST /lexicons/<lexiconId>/words`	返回`wordId`
查看词条	`GET /lexicons/<lexiconId>/words/<wordId>`
修改词条	`PATCH /lexicons/<lexiconId>/words/<wordId>`
删除词条	`DELETE /lexicons/<lexiconId>/words/<wordId>`

4.1.1 查看系统词典#

GET /sys_lexicons

获取系统词典信息。

请求消息

无

响应消息

{
  "sysLexicons": [
    {
      // 系统词典，不会返回 "id"
      "name": "SYS.city",
      "description": "国内城市",
      "representWord": "北京"
    },
    {
      ...
    }
  ]
}

4.1.2 查看租户词典#

GET /lexicons

获取本租户下所有的词典，包括自定义词典、简单词典。

请求消息

无

响应消息

{
  "lexicons": [
    {
      ... // 每一个都类似单独查询某个词典的返回
    },
    {
      ...
    }
  ]
}

4.1.3 创建词典#

POST /lexicons

请求消息

参数	类型	必选	说明
name	String	是	词典名称，同一租户下的词典名称不能重复
description	String	否	词典描述
type	String	否	词典类型 `STANDARD`(缺省)：标准词典 `DYNAMIC`: 动态词典 `SIMPLE`: 简单词表类



representWord	String	否	此词典的代表词, `SIMPLE` 类型的词典无需提供代表词
matchVar	String	否	动态词典的匹配变量 `DYNAMIC` 类型的词典必须提供此字段，且不能为空 `SIMPLE` 和 `STANDARD` 类型的词典此字段为空(缺省)

关于词典的类型和代表词、匹配变量的含义，请参见 “基本概念 - 词典”。 "系统词典" 是系统预置的，因此无法通过此接口创建。

{
  "name": "bankCard",
  "description": "银行卡名称",
  "type": "DYNAMIC",
  "representWord": "牡丹卡",
  "matchVar": "bank"
}

响应消息

{
  "created" : {
    "id": 1226 // lexiconId
  }
}

4.1.4 查看词典#

GET /lexicons/<lexiconId>

查看本租户创建的词典。如果是动态词典，会同时返回所有的动态类别。

此接口不会返回具体的词条。

请求消息

无

响应消息

{
  "id": 1226,
  "name": "bankCard",
  "description": "银行卡名称",
  "representWord": "牡丹卡",
  "type": "DYNAMIC",
  "matchVar": "bank",
  "dynamicClasses": [
    {
      ... // 同查看动态类别响应
    }
  ]
}

4.1.5 查看词典的所有词条#

GET /lexicons/<lexiconId>/words

标准词典、简单词典会返回此词典下所有的词条。动态词典也会根据请求参数，返回一个动态类别下的词条，不会返回此词典下所有动态类别的词条。

请求参数

参数	类型	必选	说明
dynamic_class_name	String	是	动态类别名称

例如：GET .../lexicons/1000/words?dynamci_class_name=beijing

如果是标准词典/简单词典
- 没有 dynamic_class_name 参数，返回此词典的所有词条
- 有 dynamic_class_name 参数，忽略此参数（可以给出 warning 信息），返回此词典的所有词条
如果是动态词典
- 没有 dynamic_class_name 参数，返回 404 NOT FOUND
- 有 dynamic_class_name 参数
  - 正确参数，则显示这一个动态类别下的所有词条
  - 如果没有找到此动态类别，返回 404 NOT FOUND
请求消息

无

响应消息

{
  "wordLists": [
    {
      "id": 10001,
      "wordList": "借记卡\t牡丹灵通卡",
    },
    {
      "id": 10002,
      "wordList": "信用卡\t牡丹信用卡"
    }
  ],
  "dynamicClass": { // 如果是动态词典，且指定了 `dynamic_class_name`， 返回对应的动态类别信息
    ... // 同 查看动态类别 返回  
  }
}

4.1.6 修改词典#

PATCH /lexicons/<lexiconId>

请求消息

可修改字段：name, description, representWord, matchVar。

不支持修改 type。

所有字段都是可选项，具体说明请参见“创建词典”。

约束

词典仅允许在没有被词槽引用的情况下修改名称和代表词，否则返回 403 Forbidden

响应消息

{
  "updated": {
    "id": 1226
  }
}

4.1.7 删除词典#

DELETE /lexicons/<lexiconId>

请求消息

无

约束

仅允许删除没有被词槽引用的词典

响应消息

{
  "deleted": {
    "id": 1226
  }
}

4.1.8 创建动态类别#

POST /lexicons/<lexiconId>/dynamic_classes

只有 lexiconId 的类型是动态词典的才能够创建动态类别。

请求消息

参数	类型	必选	说明
name	String	是	动态类别名称，同一词典下的动态类型名称不能重复
description	String	否	动态类别描述
matchValue	String	是	匹配变量的值，同一动态词典下不能重复可以为空，表示缺省动态类别，当无对应的匹配变量或者此变量无法匹配到值时，使用此类别的动态词典
matchValue	String	是

{
  "name": "ICBC_bankcard",
  "description": "工商银行银行卡动态词典",
  "matchValue": "ICBC",
}

响应消息

{
  "created" : {
    "id": 226 // dynamicId
  }
}

4.1.9 查看动态类别#

GET /lexicons/<lexiconId>/dynamic_classes/<dynamicId>

请求消息

无

响应消息

{
  "id": 226,
  "name": "ICBC_bankcard",
  "description": "工商银行银行卡动态词典",
  "matchValue": "ICBC",
}

4.1.10 修改动态类别#

PATCH /lexicons/<lexiconId>/dynamic_classes/<dynamicId>

请求消息

同创建动态类别

响应消息

{
  "updated": {
    "id": 1226
  }
}

4.1.11 删除动态类别#

DELETE /lexicons/<lexiconId>/dynamic_classes/<dynamicId>

请求消息

无

响应消息

{
  "deleted": {
    "id": 1226
  }
}

4.1.12 创建词条#

POST /lexicons/<lexiconId>/words

请求消息

参数	类型	必选	说明
content	String	是	词条内容
dynamicClassId	Integer	否	如果 `lexiconId` 是动态词典，必须有此项

对于标准词典或动态词典，每个词条可能有多个词汇，第一个词为标准词，后面可以有多个同义词（别称），以 \t 分隔。对于简单词表类，每个词条只有一个词汇。

一个标准词典里，或者一个简单词表类词典里，或者一个动态词典的一个类别的词典里，所有的词汇都不能重复。

{
  "content": "借记卡\t牡丹灵通卡",
  "dynamicClassId": 3232
}

响应消息

{
  "created": {
    "id": 1226 //wordId
  }
}

4.1.13 查看词条#

GET /lexicons/<lexiconId>/words/<wordId>

请求消息

无

响应消息

{
  "id": 1233,
  "content": "借记卡\t牡丹灵通卡",
  "dynamicClass": { // 如果属于动态词典，有此项
    ... // 同查看动态类别返回
  }
}

4.1.14 修改词条#

PATCH /lexicons/<lexiconId>/words/<wordId>

只能修改 content 项，不能修改动态类别

请求消息

同创建词条

响应消息

{
  "updated": {
    "id": 1226
  }
}

4.1.15 删除词条#

DELETE /lexicons/<lexiconId>/words/<wordId>

请求消息

无

响应消息

{
  "deleted": {
    "id": 1226
  }
}

4.2 问题#

接口说明	接口	备注
创建问题子资源	无独立接口	返回 `questionId`
删除问题子资源	无独立接口
查看问题	`GET /questions/<questionId>`
修改问题	`PATCH /questions/<questionId>`
添加扩展问	`POST /questions/<questionId>/ext_questions`	返回 `extQuestionId`
查看扩展问	`GET /questions/<questionId>/ext_questions/<extQuestionId>`
修改扩展问	`PATCH /questions/<questionId>/ext_questions/<extQuestionId>`
删除扩展问	`DELETE /questions/<questionId>/ext_questions/<extQuestionId>`

不支持单独创建问题和删除问题的接口，创建问题和删除问题总是在其所属资源下按照子资源方式创建和删除。由于子资源处理方式是一致的，这里也列出了子资源创建的接口描述。

4.2.1 创建问题子资源#

请求消息

请求消息是一个 Question 结构。具体结构描述请参见基本概念-问题。

一个问题下面的标准问和扩展问的内容都不能重复。

{
  "text": "标准问",
  "extQustions": [
    {
      "text": "扩展问1",
    },
    {
      "text": "扩展问2"
    }
  ]
}

响应消息

{
  "created": {
    "id": 10303,
    "extQuestionIds": [10000, 100001]
  }
}

4.2.2 删除问题子资源#

请求消息

无

响应消息

{
  "deleted": {
    "id": 10303,
    "extQuestionIds": [10000, 100001]
  }
}

4.2.3 查看问题#

GET /questions/<questionId>

会展开其下所有扩展问

请求消息

无

响应消息

{
  "id": 19393, // 问题id
  "text": "标准问",
  "extQuestions": [
    {
      "id": 29832,
      "text": "扩展问1"
    },
    {
      "id": 29833,
      "text": "扩展问2"
    }
  ]
}

4.2.4 修改问题#

PATCH /questions/<questionId>

只能修改标准问的text 项。

请求消息

{
  "text": "问题内容", // 标准问
}

响应消息

{
  "updated": {
    "id": 19393 // 问题id
  }
}

4.2.5 添加扩展问#

POST /questions/<questionId>/ext_questions

创建一个扩展问，并将其加到标准问下面。

请求消息

{
  "text": "扩展问内容"
}

响应消息

{
  "created": {
    "id": 19393 // 扩展问题id
  }
}

4.2.6 查看扩展问#

GET /questions/<questionId>/ext_questions/<extQuestionId>

请求消息

无

响应消息

{
  "id": 129398, // 扩展问id
  "text": "扩展问1" // 扩展问内容
}

4.2.7 修改扩展问#

PATCH /questions/<questionId>/ext_questions/<extQuestionId>

请求消息

{
  "text": "扩展问内容"
}

响应消息

{
  "updated": {
    "id": 19393 // 扩展问题id
  }
}

4.2.8 删除扩展问#

DELETE /questions/<questionId>/ext_questions/<extQuestionId>

删除扩展问，并从标准问的扩展问集合中删除

请求消息

无

响应消息

{
  "delete": {
    "id": 19393 // 扩展问题id
  }
}

4.3 标签#

接口说明	接口	备注
查看标签组列表	`GET /tag_groups`
创建标签组	`POST /tag_groups`	返回 `tagGroupId`
查看标签组	`GET /tag_groups/<tagGroupId>`
修改标签组	`PATCH /tag_groups/<tagGroupId>`
删除标签组	`DELETE /tag_groups/<tagGroupId>`
创建标签	`POST /tag_groups/<tagGroupId>/tags`	返回 `tagId`
查看标签	`GET /tag_groups/<tagGroupId>/tags/<tagId>`
修改标签	`PATCH /tag_groups/<tagGroupId>/tags/<tagId>`
删除标签	`DELETE /tag_groups/<tagGroupId>/tags/<tagId>`

4.3.1 查看标签组列表#

GET /tag_groups

一个租户下不会很多，不做分页处理，标签列表不展开。

请求消息：

无

响应消息：

{
  "tagGroups": [
    {
      "id": 20000,
      "name": "channel",
      "description": "渠道",
      "exclusive": true // 互斥
    },
    {
      "id": 20001,
      "name": "color",
      "description": "颜色",
      "exclusive": false // 非互斥
    }
  ]
}

4.3.2 创建标签组#

POST /tag_groups

请求消息：

参数	类型	必选	说明
name	String	是	标签组名称，同一个租户下不能重复
description	String	否	标签组描述
exclusive	Boolean	否	此标签组中的标签是否是互斥的 true(缺省)：互斥 false：不互斥

{
  "name": "color",
  "description": "颜色",
  "exclusive": false // 非互斥
}

响应消息：

{
  "created": {
    "id": 10000
  }
}

4.3.3 查看标签组#

GET /tag_groups/<tagGroupId>

查看标签组信息，其下标签需要展开。

请求信息：

无

响应消息：

{
  "id": 20000,
  "name": "channel",
  "description": "渠道",
  "exclusive": true, // 互斥
  "tags": [
    {
      "id": 9394,
      "name": "webchat",
      "description": "微信",
    },
    {
      "id": 8394,
      "name": "text",
      "description": "文本",
    }
  ]
}

4.3.4 修改标签组#

PATCH /tag_groups/<tagGroupId>

可修改 name, description

请求消息

{
  "name": "xxxx",
  "description": "新描述"
}

4.3.5 删除标签组#

DELETE /tag_groups/<tagGroupsId>

删除标签组和其下所有标签，要检查是否有答案关联词标签组。

请求消息

无

响应消息

{
  "deleted": {
    "id": 19393
  }
}

4.3.6 创建标签#

POST /tag_groups/<tagGroupsId>/tags

请求消息

参数	类型	必选	说明
name	String	是	标签名称，一个标签组下面的标签不能重复
description	String	否	标签描述

{
  "name": "wechat",
  "description": "微信"
}

响应消息

{
  "created":{
    "id": 9394 // tagId
  }
}

4.3.7 查看标签#

GET /tag_groups/<<tagGroupId>/tags/<tagId>

请求消息

无

响应消息

{
  "id": 9394,
  "name": "webchat",
  "description": "微信"
}

4.3.8 修改标签#

PATCH /tag_groups/<tagGroupId>/tags/<tagId>

可以修改 name, description

请求消息

同“创建标签”

响应消息

{
  "updated": {
    "id": 9394
  }
}

4.3.9 删除标签#

DELETE /tag_groups/tags/<tagId>

删除标签，并从其所属标签组中删除。要检查是否有答案关联此标签。

请求消息

无

响应消息

{
  "deleted": {
    "id": 9394
  }
}

4.4 回复#

接口说明	接口	备注
创建回复子资源	无独立接口	返回 `responseId`
删除问题子资源	无独立接口
查看回复	`GET /responses/<responseId>`
修改回复	`PATCH /responses/<responseId>`
创建答案	`POST /responses/<responseId>/answers`	返回 `answerId`
查看答案	`GET /responses/<responseId>/answers/<answerId>`
修改答案	`PATCH /responses/<responseId>/answers/<answerId>`
删除答案	`DELETE /responses/<responseId>/answers/<answerId>`

不支持单独创建问题和删除回复的接口，创建回复和删除回复总是在其所属资源下按照子资源方式创建和删除。由于子资源处理方式是一致的，这里也列出了子资源创建的接口描述。

4.4.1 创建回复子资源#

请求消息

请求消息是一个 Response 结构。具体结构描述请参见基本概念-问题。

{
  "returnType": "RANDOM", // RANDOM or FIRST
  "answers": [
    {
      "type": "TEXT", // TEXT, TTS, AUDIO, VIDEO, HTML
      "content": "{$name}，您好，有什么可以帮您的？",
      "tags": [ // 可选，但必须是有效的标签组和标签，使用 `标签组:标签` 格式
        "channel:wechat", "color:red", "color:blue",
      ]
    },
    {
      "type": "TEXT",
      "content": "xxxx",
      "cmd": "xxxx", // 可选
      "tags": [ // 可选，但必须是有效的标签组和标签，使用 `标签组:标签` 格式
        "channel:text"
      ]
    }
  ]  
}

响应消息

{
  "created": {
    "id": 1030,
    "answerIds": [
      1939, 1940, 1941
    ]
  }
}

4.4.2 删除回复子资源#

请求消息

无

响应消息

{
  "deleted": {
    "id": 1030,
    "answerIds": [
      1939, 1940, 1941
    ]
  }
}

4.4.3 查看回复#

GET /responses/<responseId>

请求消息

无

响应消息

{
  "id": 5000, //responseId
  "returnType": "RANDOM",
  "answers": [
    {
      "id": 15000, //answerId
      "type": "TEXT",
      "content": "{$name}，您好，有什么可以帮您的？",
      "tags":[
          "channel:wechat", "color:red", "color:green"
       ]
    },
    {
      "id": 15001, // answerId
      "type": "TEXT",
      "content": "xxxx",
      "cmd": "xxxx",
      "tags": [
          "channel:text"
      ]
    }
  ]  
}

4.4.4 修改回复#

PATCH /responses/<responseId>

可修改字段 returnType

请求消息

{
  "returnType": "FIRST"
}

响应消息

{
  "updated": {
    "id": 5000
  }
}

4.4.5 创建答案#

POST /responses/<responseId>/answers

请求消息

{
  "type": "TEXT",
  "content": "xxxx",
  "cmd": "xxxx",
  "tags": [
      "channel: text"
  ]
}

响应消息

{
  "created": {
    "id": 15002 // answerId
  }
}

4.4.6 查看答案#

GET /responses/<responseId>/answers/<answerId>

请求消息

无

响应消息

{
  "id": 12333, // answerId
  "type": "TEXT",
  "content": "xxxx",
  "cmd": "xxxx",
  "tags": [
      "channel: text"
  ]
}

4.4.7 修改答案#

PATCH /responses/<responseId>/answers/<answerId>

请求消息

可修改字段：content, cmd, tags，修改tags时会将原来的标签全部替换。

不支持修改 type 字段。

响应消息

{
  "updated": {
    "id": 15002 // answerId
  }
}

4.4.8 删除答案#

DELETE /responses/<responseId>/answers/<answerId>

请求消息

无

响应消息

{
  "deleted": {
    "id": 15002 // answerId
  }
}

4.5 处理步骤#

接口说明	接口	备注
创建处理步骤子资源	无独立接口	返回 `procId`
删除处理步骤子资源	无独立接口
查看处理步骤	`GET /processors/<procId>`
修改处理步骤	`PATCH /processors/<procId>`

不支持单独创建处理步骤和删除处理步骤的接口，创建处理步骤和删除处理步骤总是在其所属资源下按照子资源方式创建和删除。由于子资源处理方式是一致的，这里也列出了子资源创建的接口描述。

4.5.1 创建处理步骤子资源#

请求消息

请求消息是一个 Processor 结构，具体结构描述请参见基本概念-处理步骤。

{
  "type": "SIMPLE",
  "content": {
    "ops": [
      {
        "condition": "param1 >= 3",
        "evals": [
          "param2 = 8",
          "param3 = param1",
        ]
      }
    ]
  }
}

响应消息

{
  "created": {
    "id": 2999  // procId
  }
}

4.5.2 删除处理步骤子资源#

请求消息

无

响应消息

{
  "deleted": {
    "id": 2999  // procId
  }
}

4.5.3 查看处理步骤#

GET /processors/<procId>

请求消息

无

响应消息

根据处理步骤的类型不同，有不同的返回格式.

{
  "id": 11233, //procId
  "type": "SIMPLE",
  "content": {
    "ops": [
      {
        "condition": "param1 >= 3",
        "evals": [
          "param2 = 8",
          "param3 = param1",
        ]
      }
    ]
  }
}

{
  "id": 11233, //procId
  "type": "WEBAPI",
  "content": {
    "method": "POST",
    "url": "http://www.example.com/test/{{global.param1}}/info?foo={{param2}}",
    "headers": [
      "X-Custom-Info: {{slots.corp.normValue}}"
    ],
    "body": "{ \"bank\" : \"{{user.bank}}\", \"balance\" : {{balance}} }",
    "result": "webapiResult"
  }
}

{
  "id": 11233, //procId
  "type": "FAAS",
  "content": {
    "lang": "javascript",
    "code": "if (user.province=\"江苏\") {\ncapital=\"南京\"; \n}"
  }
}

4.5.4 修改处理步骤#

PATCH /processors/<procId>

请求消息

字段： type, content。 content 总是作为整体修改，不能单独修改其下的某个字段内容。

可以单独修改 content。但如果修改 type，也必须同时提供 content 字段。

响应消息

{
  "udpated": {
    "id": 11233 //procId
  }
}

4.6 问答目录#

接口说明	接口	备注
查看问答领域	`GET /qa_domains/`
创建问答领域	`POST /qa_domains/`	返回 `domainId`，所有接受 `dirId`的地方也会接受`domainId`
创建问答子目录	`POST /qa_dirs/<dirId>/qa_dirs`	返回 `dirId`
查看问答目录	`GET /qa_dirs/<dirId>`
修改问答目录	`PATCH /qa_dirs/<dirId>`
删除问答目录	`DELETE /qa_dirs/<dirId>`
创建问答对	`POST /qa_dirs/<dirId>/qa_pairs`	返回 `pairId`
查看问答对	`GET /qa_dirs/<dirId>/qa_pairs/<pairId>`
修改问答对	`PATCH /qa_dirs/<dirId>/qa_pairs/<pairId>`
删除问答对	`DELTE /qa_dirs/<dirId>/qa_pairs/<pairId>`
查看问答目录下的所有问答对	`GET /qa_dirs/<dirId>/qa_pairs`
移动问答目录	`PATCH /qa_dirs/<dirId>/`

4.6.1 查看问答领域#

GET /qa_domains/

查看顶层的问答目录，也即问答领域。

会返回其下所有子节点，但不会返回挂接的问答对。

请求消息

无

响应消息

{
  "qaDomains": [
    {
      ... // 每一个都类似单独查询某个问答目录的返回
    },
    {
      ...
    }
  ]
}

4.6.2 创建问答领域#

POST /qa_domains/

创建顶层的问答目录，一般也称为问答领域。

请求消息

参数	类型	必选	说明
name	String	是	问答领域名称
description	String	否	问答领域描述

{
  "name": "software",
  "description": "计算机软件",
}

响应消息

{
  "created" : {
    "id": 12 // dirId
  }
}

4.6.3 创建问答目录#

POST /qa_dirs/<dirId>/qa_dirs

请求消息、响应消息和创建问答领域一致，但会以 dirId 为父节点进行创建。

<dirId> 处也可以是创建问答领域返回的 <domainId>

4.6.4 查看问答目录#

会返回其下所有子节点，但不会返回挂接的问答对。

GET /qa_dirs/<dirId>

请求消息

无

响应消息

{
  "id": 10, // dirId
  "name": "software",
  "description": "计算机软件",
  "children": [
    {
      "id": 101,
      "name": "language",
      "description": "编程语言",
      "children" : [
        {
          "id": 222,
          "name": "C++",
          "description": "C++语言"
        },
        {
          "id": 223,
          "name": "Python",
          "description": "Python 语言"
        }
      ]
    },
    {
      "id": 102,
      "name": "database",
      "description": "数据库",
      "children": [
        {
          "id": 555,
          "name": "MySQL",
          "description": "Mysql"
        }
      ]
    }
  ]
}

4.6.5 修改问答目录#

PATCH /qa_dirs/<dirId>

可以修改 name, description。

请求消息

同创建问答目录

响应消息

{
  "updated": {
    "id": 1000
  }
}

4.6.6 删除问答目录#

DELETE /qa_dirs/<dirId>

删除问答目录时，如果本问答目录或其下任何一个下面的目录被绑定在某个问答库技能上时，将无法删除。而如果其上面的目录被绑定，则其技能对应信息会自动更新。

请求消息

无

响应消息

{
  "deleted": {
    "id": 1000
  }
}

4.6.7 创建问答对#

POST /qa_dirs/<dirId>/qa_pairs

请求消息

参数	类型	必选	说明
questoin	Object of Question	是	问题
response	Object of Response	是	回复
enabled	Boolean	否	是否启用 true (缺省)：启用；false：不启用
enabled	Boolean	否	是否启用 true (缺省)：启用；false：不启用
effectTime	String	否	生效时间。如果不为空，需遵循RFC 3339规范。缺省为空，表示无生效时间
effectTime	String	否	生效时间。如果不为空，需遵循RFC 3339规范。缺省为空，表示无生效时间
invalidTime	String	否	取消时间。如果不为空，需遵循RFC 3339规范。缺省为空，表示无取消时间
invalidTime	String	否	取消时间。如果不为空，需遵循RFC 3339规范。缺省为空，表示无取消时间

如果 effectTime 和 invalidTime 同时存在，invalidTime 必须晚于 effectTime。

{
  "question": {
    ...
  },
  "response": {
    ...
  },
  "enabled": true,
  "effectTime": "2019-03-01T10:58:37+08:00", // 可为空
  "invalidTime": "2019-05-30T10:58:37+08:00" // 可为空
}

响应消息

{
  "created": {
    "id": 93944, // pairId
    "question": {
      "id": 2993,  // questionId
      "extQuestionIds": [
        5233, 5234, 5235
      ]
    },
    "response": {
      "id": 9399, // responseId
      "answerIds": [
        2393, 393, 0330
      ]
    }
 }
}

4.6.8 查看问答对#

GET /qa_dirs/<dirId>/qa_pairs/<pairId>

请求参数

参数	类型	必选	说明
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开

示例:

GET .../qa_dirs/1233/qa_pairs/1233?detail=true

请求消息

无

响应消息

{
  "question": {
    "id": 19303, // 问题id
    ... // 可能会展开
  },
  "response": {
    "id": 1298934, // 回复id
    ... // 可能会展开
  },
  "enabled": true,
  "effectTime": "2019-03-01T10:58:37+08:00", // 可为空
  "invalidTime": "2019-05-30T10:58:37+08:00" // 可为空
}

4.6.9 修改问答对#

PATCH /qa_dirs/<dirId>/qa_pairs/<pairId>

请求消息

可修改字段：enabled, effectTime, invalidTime。

所有字段都是可选项，具体说明请参见“创建意图”。

question, response 使用相应的子资源修改接口进行修改。

响应消息

{
  "updated": {
    "id": 19293 // pairId
  }
}

4.6.10 删除问答对#

DELTE /qa_dirs/<dirId>/qa_pairs/<pairId>

请求消息

无

响应消息

{
  "deleted": {
    "id": 93944, // pairId
    "question": {
      "id": 2993,  // questionId
      "extQuestionIds": [
        5233, 5234, 5235
      ]
    },
    "response": {
      "id": 9399, // responseId
      "answerIds": [
        2393, 393, 0330
      ]
    }
  }
}

4.6.11 查看问答目录下的所有问答对#

GET /qa_dirs/<dirId>/qa_pairs/

只获取当前文档目录绑定的问答对，不支持递归子目录，支持分页返回，支持条件过滤。

请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
detail	Boolean	否	当前查询返回问答对时，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开为false的时候，也需要显示扩展问和答案的Id


enabled	Boolean	否	显示启用或停用的问答对 all(缺省): 所有；enabled: 仅显示启用; disabled: 仅显示停用
enabled	Boolean	否	显示启用或停用的问答对 all(缺省): 所有；enabled: 仅显示启用; disabled: 仅显示停用
effective	Boolean	否	显示当前生效或不生效的问答对 all(缺省): 所有；effective：仅显示生效；invalid: 仅显示无效
effective	Boolean	否	显示当前生效或不生效的问答对 all(缺省): 所有；effective：仅显示生效；invalid: 仅显示无效

例如：

GET .../qa_dirs/123/qa_pairs?offset=200&limit=100&detail=false

请求消息

无

响应消息

{
  "total": 1023, // 总的问答对数量
  "offset": 100, // 返回问答对的位置
  "limit": 50, // 返回问答对的数量上限，和前端指定的一致
  "qaPairs": [ // 具体数量由 qaPairs 数组确定，有可能小于limit
    {
      "question": {
        "id": 19303, // 问题id
        ... // 可能会展开
        "extQuestions": [
          {
            "id": 200000,
            ... // 可能会展开
          },
          {
            ...
          }
        ]
      },
      "response": {
        "id": 1298934, // 回复id
        ... // 可能会展开
        "answers": [
          {
            "id": 3000,
            ... // 可能会展开
          }
        ]
      },
      "enabeld": true,
      "beginTime": "2019-03-01T10:58:37+08:00", // 可为空
      "endTime": "2019-05-30T10:58:37+08:00" // 可为空
    },
    {
      ...
    },
  ]
}

4.6.12 移动问答目录#

PATCH /qa_dirs

将问答库的某个节点移动到另外一个节点之下。

请求消息

参数	类型	必选	说明
qadirId	Integer	是	要移动的问答目录
newParentId	Integer	是	移动到此问答目录之下

将 qadirId 代表的问答目录移动到 newParentId 代表的问答目录下面，作为 newParentId 的子节点。 newParentId 为 0 则表示 qadirId 变为顶层的问答目录，也即问答领域。

如下几种情况，会返回 412 Precondition Failed

newParentId 中有与 qadirId 同名的节点
newParentId 与 qadirId 相同，或者是其后代节点
newParentId 已经是 qadirId 的父节点

{
  "qadirId": 303,
  "newParentId": 303
}

响应消息

{
  "result": "ok"
}

4.7 任务问题#

接口说明	接口	备注
获取所有任务问题	`GET /task_questions/`
创建任务问题	`POST /task_questions/`	返回 `tqId`
查看任务问题	`GET /task_questions/<tqId>`
修改任务问题	`PATCH /task_questions/<tqId>`
删除任务问题	`DELETE /task_question/<tqId>`

4.7.1 获取所有任务问题#

GET /task_questions/

请求参数

参数	类型	必选	说明
offset	Integer	否	当前查询返回列表的起始偏移，缺省为0
limit	Integer	否	当前查询返回列表数量，缺省为50，范围为 [10-1000]
label	String	否	只显示所需标签的问题，需要进行URL转义
detail	Boolean	否	当前查询返回任务问题时，是否要展开显示问题、扩展问 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回任务问题时，是否要展开显示问题、扩展问 true(缺省): 展开；false: 不展开

GET .../task_questions?offset=100&limit=50&detail=true&label=YES

请求消息

无

响应消息

{
  "total": 12993, // 总数
  "offset": 100, // 返回任务问题的起始偏移
  "limit": 50, // 返回数量上限，和前端指定的一致
  "taskQuestions": [ // 具体数量由 taskQuestions 数组确定，有可能小于 limit
    {
      "id": 2939,
      "label": "肯定",
      "question": {
        "id": 939,
        ... // 可能有详细信息
        "extQuestions": [
          {
            "id": 3544,
            ... // 可能有详细信息
          },
          {
            ...
          }
        ]
      }
    },
    {
      ...
    }
  ]
}

4.7.2 创建任务问题#

POST /task_questions/

请求消息

参数	类型	必选	说明
label	String	是	任务问题的标签
question	Obejct of Question	是	任务问题的具体内容

{
  "label": "肯定答复",
  "question": {
    "text": "是的",
    "extQustions": [
      { "text": "是" },
      { "text": "对的" },
      { "text": "对" }
    ]
  }
}

响应消息

{
  "created": {
    "id": 1939,   // tqId
    "question": {
      "id": 2993,
      "extQuestionIds": [
        5233, 5234, 5235
      ]
    }
  }
}

4.7.3 查看任务问题#

GET /task_questions/<tqId>

问题和扩展问总是展开

请求消息

无

响应消息

{
  "id": 1939,
  "label": "肯定答复",
  "question": {
    "id": 2993,
    "text": "是的",
    "extQustions": [
      { "id": 5223, "text": "是" },
      { "id": 5224, "text": "对的" },
      { "id": 5225, "text": "对" }
    ]
  }
}

4.7.4 修改任务问题#

PATCH /task_questions/<tqId>

请求消息

可修改字段： label。问题和扩展问内容使用子资源的修改接口进行修改。

响应消息

{
  "updated": {
    "id": 2988 // tqId
  }
}

4.7.5 删除任务问题#

DELETE /task_question/<tqId>

当任务问题被场景引用时，无法删除。删除被应用的任务问题时，会返回 409 Conflict。

请求消息

无

响应消息

{
  "deleted": {
    "id": 2988, // tqId
    "question" : {
      "id": 2500,
      "extQuestionIds": [
        5223, 5224, 5225
      ]
    }
  }
}

4.8 知识图谱#

10D.0 暂不支持知识图谱技能

4.9 意图#

意图相关的接口如下：

接口说明	接口	备注
创建意图	`POST /intents`	返回 `intentId`
创建意图子资源	`POST /intents/<intentId>/confirm_response`
	`POST /intents/<intentId>/retry_response`
	`POST /intents/<intentId>/failed_response`
	`POST /intents/<intentId>/processor`
删除意图子资源	`DELETE /intents/<intentId>/confirm_response`
	`DELETE /intents/<intentId>/retry_response`
	`DELETE /intents/<intentId>/failed_response`
	`DELETE /intents/<intentId>/processor`
查看意图	`GET /intents/<intentId>`
修改意图	`PATCH /intents/<intentId>`
删除意图	`DELETE /intents/<intentId>`
创建词槽	`POST /intents/<intentId>/slots`	返回 `slotId`
创建词槽子资源	`POST /intents/<intentId>/slots/<slotId>/confirm_response`
删除词槽子资源	`DELETE /intents/<intentId>/slots/<slotId>/confirm_response`
查看词槽	`POST /intents/<intentId>/slots/<slotId>`
修改词槽	`PATCH /intents/<intentId>/slots/<slotId>`
修改词槽顺序	`PATCH /intents/<intentId>/slots_order`
删除词槽	`DELETE /intents/<intentId>/slots/<slotId>`

4.9.1 创建意图#

请求消息

参数	类型	必选	说明
name	String	是	意图名称，不能重复
description	String	否	意图描述
question	Object Of Question	是	意图问题
response	Object of Response	是	最终回复
slots	Array of Slot	否	词槽定义
confirmResponse	Object of Response	否	意图确认话术
retryMaxTimes	Integer	否	最大重试次数，缺省为3，范围 [0-5]
retryResponse	Obejct of Response	否	重试话术
failedResponse	Obejct of Response	否	失败话术
processor	Obejct of Processor	否	自定义处理步骤
checkOtherSkill	Boolean	否	当无法命中本技能时，是否允许跳转到其它技能 true(缺省)：允许；false：不允许
checkOtherSkill	Boolean	否	当无法命中本技能时，是否允许跳转到其它技能 true(缺省)：允许；false：不允许
autoRecover	Boolean	否	当跳转到问答型技能后，是否自动恢复 true(缺省)：自动恢复；false：不自动恢复
autoRecover	Boolean	否	当跳转到问答型技能后，是否自动恢复 true(缺省)：自动恢复；false：不自动恢复
repeatWhenRecover	Boolean	否	当自动恢复时，是否重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRecover	Boolean	否	当自动恢复时，是否重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRetry	Boolean	否	当重试时，如果有重试话术的情况下，是否还要重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRetry	Boolean	否	当重试时，如果有重试话术的情况下，是否还要重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术

retryResponse 和 repeatWhenRetry 定义了重试时候的回复情况，有三种情况：

定义了 retryResponse，repeatWhenRetry 为 false：仅回复重试话术
定义了 retryResponse，repeatWhenRetry 为 true：回复重试话术 + 上次话术
未定义 retryResponse：回复上次话术

{
  "name": "TICKET",
  "description": "订机票",
  "question": {
    ... // 同创建问题请求
  },
  "slots": [
    {
      ... // 同创建词槽 请求信息
    },
    {
      ... // 同创建词槽 请求信息
    }
  ],
  "confirmResponse": {
    ... // 意图确认话术, 同 创建回复 请求信息
  },
  "processor": {
    ... // 自定义处理步骤，基本同 处理节点 请求信息
  },
  "response": {
    ... // 最终回复， 同 创建回复 请求信息
  },
  "retryResponse": {
    ... // 重试话术, 同 创建回复 请求信息
  },
  "retryMaxTimes":  3, // 最大重试次数
  "failedResponse": {
    ... // 失败话术, 同 创建回复 请求信息
  },
  "checkOtherSkill": true, // 是否允许跳转到其它技能
  "autoRecover": true, // 如果跳出此技能后是到达了问答型技能，是否自动恢复
  "repeatWhenRecover": true, // 如果自动恢复了，是否重复上次话术
  "repeatWhenRetry": true // 如果重试时，在有重试话术的情况下是否还要重复上次话术
}

响应消息

{
  "created": {
    "id": 1999, // intentId
    "question": {
      "id": 1111, //questionId
    },
    "slots": [
      {
        "id": 1888, // slotId
        "elicitResponse": {
          "id": 9393, // responseId
          "answerIds": [...]
        },
        "confirmResponse": {
          "id": 9393, // responseId
          "answerIds": [...]
        }
      }
    ],
    "confirmResponse": {
      "id": 1232, // responseId
      "answerIds": [...]
    },
    "response": {
      "id": 1234, // responseId
      "answerIds": [...]
    },
    "retryResponse": {
      "id": 1235, // responseId
      "answerIds": [...]
    },
    "failedResponse": {
      "id": 1236, // responseId
      "answerIds": [...]
    }
  }
}

4.9.2 创建意图子资源#

创建意图确认话术: POST /intents/<intentId>/confirm_response

创建重试话术: POST /intents/<intentId>/retry_response

创建失败话术: POST /intents/<intentId>/failed_response

创建处理步骤: POST /intents/<intentId>/processor

使用这些接口来创建意图的子资源。只有在创建意图时没有指定这些资源时，才能用这些接口创建，如果已经存在，则返错。

创建话术的接口请求消息和响应消息参见创建回复子资源。

创建处理步骤的接口请求消息和响应消息参见创建处理步骤子资源。

4.9.3 删除意图子资源#

删除意图确认话术：DELETE /intents/<intentId>/confirm_response

删除重试话术：DELETE /intents/<intentId>/retry_response

删除失败话术：DELETE /intents/<intentId>/failed_response

删除处理步骤：DELETE /intents/<intentId>/processor

使用这些接口删除意图的子资源。

删除话术的接口请求消息和响应消息参见删除回复子资源。

删除处理步骤的接口请求消息和响应消息参见删除处理步骤子资源。

4.9.4 查看意图#

GET /intents/<intentId>

请求参数

参数	类型	必选	说明
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开

示例：

GET .../intents/6000?detail=false

请求消息

无

响应消息

如果 detail 为 true ，则所有问题、扩展问、回复、答案（包括 Slot 里面的回复、答案）对象都会展开，否则只输出 id。

{
  "id": 1999,
  "name": "TICKET",
  "description": "订机票",
  "question": {
    "id": 1283, // 用户表述，questionId
    // 可能展开
    "extended": [ // 扩展问
      {
        "id": 19293,
        // 可能展开
      }
    ]
  },
  "slots": [
    {
      // 同下面词槽输出信息
      "id": 10050, // SlotId
      ...
    },
    {
      // 同下面词槽输出信息
      "id": 10051, // SlotId
      ...
    }
  ],
  "confirmIntentResponse": {
    "id": 19828, // 意图确认话术, response_id
    // 可能展开
  },
  "processor": {
    "id": 19933 // processorId
    ...
  },
  "response": {
    "id": 3333
    ... // 可能展开
  },
  "retryResponse": {
    "id": 10333 // 重试话术
    ... // 可能展开
  },
  "retryMaxTimes":  3, // 最大重试次数
  "failedResponse": {
    "id": 9393
    ... // 可能展开
  },
  "checkOtherSkill": true, // 是否允许跳转到其它技能
  "autoRecover": true, // 如果跳出此技能后是到达了问答型技能，是否自动恢复
  "repeatWhenRecover": true, // 如果自动恢复了，是否重复上次话术
  "repeatWhenRetry": true // 如果重试时，在有重试话术的情况下是否还要重复上次话术
}

4.9.5 修改意图#

PATCH /intents/<intentId>

所有子资源，使用资源相关的修改函数进行修改。除子资源之外的其余属性都可以修改。

请求消息

可修改字段：name, description, retryMaxTimes, checkOtherSkill, autoRecover, repeatWhenRecover, repeatWhenRetry。

所有字段都是可选项，具体说明请参见“创建意图”。

响应消息

{
  "updated": {
    "id": 1999 // intentId
  }
}

4.9.6 删除意图#

DELETE /intents/<intentId>

删除此意图和其下所有词槽，需要检查是否有技能引用此意图。

请求消息

无

响应消息

{
  "deleted": {
    "id": 1999, // slotId
  }
}

4.9.7 创建词槽#

POST /intents/<intentId>/slots

请求消息

参数	类型	必选	说明
name	String	是	词槽名称，同时也作为赋值的变量名称
description	String	是	词槽描述
required	Boolean	否	是否必须 true (缺省): 必须；false：不必须
required	Boolean	否	是否必须 true (缺省): 必须；false：不必须
lexicon	String	是	词槽绑定的词典名称
elicitResponse	Object of Response	是	追问话术
confirmResponse	Obejct of Response	否	确认话术

lexicon 为词槽绑定的词典名称，可以是以 SYS. 开头的系统词典，也可以是通过创建词典接口创建的自定义词典。此词典名称必须存在。

在一个意图中，词槽的 order 会按照加入的顺序自动递增（越小的优先级越高），不能在请求消息中指定。如果要修改词槽顺序，必须通过 “修改词槽顺序” 接口进行修改。

{
  "name": "fromCity",
  "description": "出发城市",
  "required": true,
  "lexicon": "SYS.city",
  "elicitResponse": {
    ... // 和创建回复的请求消息一致
  },
  "confirmResponse": {
    ... // 和创建回复的请求消息一致
  }
}

响应消息

{
  "created": {
    "id": 1999, // slotId
    "elicitResponse": {
      "id": 10023, // responseId
      "answerIds": [...]
    },
    "confirmResponse": {
      "id": 10024, // responseId
      "answerIds": [...]
    }
  }
}

4.9.8 创建词槽子资源#

创建词槽确认话术：POST /intents/<intentId>/slots/<slotId>/confirm_response

使用此接口可以创建词槽的确认话术，但只能是在创建词槽时没有创建时才能使用。如果已经有了，再次创建会失败。

创建话术的接口请求消息和响应消息参见创建回复子资源。

4.9.9 删除词槽子资源#

删除词槽确认话术：DELETE /intents/<intentId>/slots/<slotId>/confirm_response

使用此接口删除词槽的确认话术。

删除话术的接口请求消息和响应消息参见删除回复子资源。

4.9.10 查看词槽#

POST /intents/<intentId>/slots/<slotId>

请求参数

参数	类型	必选	说明
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回的信息中，是否要展开显示问题、扩展问、回复、答案 true(缺省): 展开；false: 不展开

请求消息

无

响应消息

如果 detail 为 true，elicitSlotResponse 和 confirmSlotResponse 会展开，否则只显示 id。

{
  "id": 1999, // slotId
  "name": "fromCity",
  "description": "出发城市",
  "required": true,
  "order": 12,
  "lexicon": "SYS.chinaCity",
  "elicitSlotResponse": {
    "id": 10023 // responseId
    ... //可能会展开
  },
  "confirmSlotResponse": {
    "id": 10024 // responseId
    ... //可能会展开
  }
}

4.9.11 修改词槽#

PATCH /intents/<intentId>/slots/<slotId>

所有子资源，使用资源相关的修改函数进行修改。

不允许直接修改 order，需要使用 “修改词槽顺序” 接口来一起修改所有词槽的顺序。

除子资源和 order 之外的其余属性可以通过此接口修改。

请求消息

可修改字段：name, description, required, lexicon。

所有字段都是可选项，具体说明请参见“创建词槽”。

响应消息

{
  "updated": {
    "id": 1999, // slotId
  }
}

4.9.12 修改词槽顺序#

使用此接口修改意图下面所有词槽的顺序。

PATCH /intents/<intentId>/slot_order

请求消息

参数	类型	必选	说明
slots	Array of Integer	是	所有词槽的Id

{
  "slots": [19393, 1233, 1233, 9393]
}

约束

slots 中的词槽Id必须是此意图所属的词槽，如果出现非法的词槽Id或者不属于此意图的词槽Id，返回错误
如果词槽Id有重复，返回错误
如果此意图还有 slots 定义的词槽之外的词槽Id，返回错误

响应消息

{
  "updated": {
    "id": 1999 // intentId
  }
}

4.9.13 删除词槽#

DELETE /intents/<intentId>/slots/<slotId>

删除词槽和其对应话术，此词槽在所属意图的问题中应该没有被引用.

请求消息

无

响应消息

{
  "deleted": {
    "id": 1999, // slotId
    "elicitSlotResponse": {
      "id": 10023, // responseId
      "answerIds": [...]
    },
    "confirmSlotResponse": {
      "id": 10024, // responseId
      "answerIds": [...]
    }
  }
}

4.10 场景#

接口说明	接口	备注
创建场景	`POST /scenes`	返回 `sceneId`
查看场景	`GET /scenes/<sceneId>`
修改场景	`PATCH /scenes/<sceneId>`
删除场景	`DELETE /scenes/<sceneId>`
修改场景子资源	`POST /scenes/<sceneId>/retry_response`
修改场景子资源	`POST /scenes/<sceneId>/failed_response`
删除场景子资源	`DELETE /scenes/<sceneId>/retry_response`
删除场景子资源	`DELETE /scenes/<sceneId>/failed_response`
创建节点	`POST /scenes/<sceneId>/nodes/`	返回 `nodeId`
查看节点	`GET /scenes/<sceneId>/nodes/<nodeId>`
修改节点	`PATCH /scenes/<sceneId>/nodes/<nodeId>`
删除节点	`DELETE /scenes/<sceneId>/nodes/<nodeId>`
创建分派节点分支	`POST /scenes/<sceneId>/nodes/<nodeId>/branches`	返回 `branchId`
查看分派节点分支	`GET /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>`
修改分派节点分支	`PATCH /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>`
删除分派节点分支	`DELETE /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>`

4.10.1 创建场景#

POST /scenes

创建一个场景

请求消息

参数	类型	必选	说明
name	String	是	场景名称，不能重复
description	String	否	场景描述
retryMaxTimes	Integer	否	最大重试次数，缺省为3，范围 [0-5]
retryResponse	Obejct of Response	否	重试话术
failedResponse	Obejct of Response	否	失败话术
autoRecover	Boolean	否	当跳转到问答型技能后，是否自动恢复 true(缺省)：自动恢复；false：不自动恢复
autoRecover	Boolean	否	当跳转到问答型技能后，是否自动恢复 true(缺省)：自动恢复；false：不自动恢复
repeatWhenRecover	Boolean	否	当自动恢复时，是否重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRecover	Boolean	否	当自动恢复时，是否重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRetry	Boolean	否	当重试时，如果有重试话术的情况下，是否还要重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术
repeatWhenRetry	Boolean	否	当重试时，如果有重试话术的情况下，是否还要重复上次话术 true：重复上次话术；false(缺省)：不重复上次话术

retryResponse 和 repeatWhenRetry 定义了重试时候的回复情况，有三种情况：

定义了 retryResponse，repeatWhenRetry 为 false：仅回复重试话术
定义了 retryResponse，repeatWhenRetry 为 true：回复重试话术 + 上次话术
未定义 retryResponse：回复上次话术

{
  "name": "催缴外呼流程",
  "description": "用于催缴外呼",
  "retryResponse": {
    ... // 重试话术, 同 创建回复 请求信息
  },
  "retryMaxTimes":  3, // 最大重试次数
  "failedResponse": {
    ... // 失败话术, 同 创建回复 请求信息
  },
  "autoRecover": true, // 如果跳出此技能后是到达了问答型技能，是否自动恢复
  "repeatWhenRecover": true, // 如果自动恢复了，是否重复上次话术
  "repeatWhenRetry": true // 如果重试时，在有重试话术的情况下是否还要重复上次话术
}

响应消息

{
  "created": {
    "id": 1999, // sceneId
    "retryResponse" : {
      "id": 1233, // responseId
      "answerIds": [...]
    },
    "failedResponse": {
      "id": 1234, // responseId
      "answerIds": [...]
    }
  }
}

4.10.2 查看场景#

GET /scenes/<sceneId>

展开node

参数	类型	必选	说明
detail	Boolean	否	返回的消息中，是否要展开节点的详情
detail	Boolean	否	true (缺省)：展开，false：不展开

示例：

GET .../scenes/2399?detail=false

请求消息

无

响应消息

{
  "id": 1999, // sceneId
  "name": "催缴外呼流程",
  "description": "用于催缴外呼",
  "retryResponse" : {
    "id": 1233 // responseId
    ... // 可能展开
  },
  "retryMaxTimes":  3, // 最大重试次数
  "failedResponse": {
    "id": 122
    ... // 可能展开
  },
  "autoRecover": true, // 如果跳出此技能后是到达了问答型技能，是否自动恢复
  "repeatWhenRecover": true, // 如果自动恢复了，是否重复上次话术
  "repeatWhenRetry": true, // 如果重试时，在有重试话术的情况下是否还要重复上次话术
  "nodes": [
    {
      "id": 3000,
      ... // 可能展开
    },
    {
      "id": 3001,
      ... // 可能展开
    }
  ]
}

4.10.3 修改场景#

PATCH /scenes/<sceneId>

请求消息

可修改字段：name, description, retryMaxTimes, autoRecover, repeatWhenRecover, repeatWhenRetry。

所有字段都是可选项，字段的具体说明请参见“创建节点”。

修改 retryResponse, failedResponse 请使用“修改回复”接口。

响应消息

{
  "updated": {
    "id": 9393
  }
}

4.10.4 删除场景#

DELETE /scenes/<sceneId>

删除场景时，删除其下所有内容

请求消息

无

响应消息

{
  "deleted" : {
    "id": 1999,
    "retryResponse": {
      "id": 1233, // reponseId
      "answerIds": [...]
    },
    "nodes": [
      {
        "id": 3000,
        ... // 如果有相关资源的话，也有子资源的id
      },
      {
        "id": 3001
        ... // 如果有相关资源的话，也有子资源的id
      }
    ]
  }
}

4.10.5 创建场景子资源#

创建重试话术：POST /scenes/<sceneId>/retry_response

创建失败话术：POST /scenes/<sceneId>/failed_response

使用这些接口来创建场景的子资源。只有在创建场景时没有指定这些资源时，才能用这些接口创建，如果已经存在，则返错。

创建话术的接口请求消息和响应消息参见创建回复子资源。

4.10.6 删除场景子资源#

删除重试话术：DELETE /scenes/<sceneId>/retry_response

删除失败话术：DELETE /scenes/<sceneId>/failed_response

使用这些接口删除场景的子资源。

删除话术的接口请求消息和响应消息参见删除回复子资源。

4.10.7 创建节点#

POST /scenes/<sceneId>/nodes/

创建不同类型的节点。

请求消息

无论创建何种类型的节点，都有如下参数：

参数	类型	必选	说明
name	String	是	节点名称，一个场景下不能重复
description	String	否	节点描述
type	String	是	节点类型 `ENTRY`：入口节点 `UNDERSTAND`：理解节点 `DISPATCH`：分派节点 `PROCESS`：处理节点 `RESPONSE`：回复节点

根据创建的节点类型不同，还有如下额外参数：

参数	类型	必选	说明
入口节点
taskQuestionIds	Array of Integer	否	命中问题的列表，在无条件入口时无需此项在有条件入口时必须存在且不为空
taskQuestionIds	Array of Integer	否	命中问题的列表，在无条件入口时无需此项在有条件入口时必须存在且不为空
nextNodeId	Integer	否	下一个节点，缺省为0，表示无下一个节点
理解节点
taskQuestionIds	Array of Integer	是	命中问题的列表，不能为空
nextNodeId	Integer	否	下一个节点，缺省为0，表示无下一个节点
分派节点
checkOtherSkill	Boolean	否	如果当前分派节点的所有分支都不能命中，是否允许跳转到其它技能 true(缺省)：允许；false：不允许
checkOtherSkill	Boolean	否	如果当前分派节点的所有分支都不能命中，是否允许跳转到其它技能 true(缺省)：允许；false：不允许
处理节点
processor	Object of Processor	是	具体的处理步骤
nextNodeId	Integer	否	下一个节点，缺省为0，表示无下一个节点
回复节点
response	Obejct of Response	是	回复内容
nextNodeId	Integer	否	下一个节点，缺省为0，表示无下一个节点

taskQuestions 必须是任务问题的ID列表。

{
  "name": "入口节点",  
  "description": "入口描述",
  "type": "ENTRY",
  "taskQuestionIds": [
    1334,29393,192993,40000
  ],
  "nextNodeId": 2233
}

{
  "name": "无入口节点",  
  "description": "无条件入口描述",
  "type": "ENTRY",
  "nextNodeId": 2233
}

{
  "name": "理解节点",  
  "description": "理解节点描述",
  "type": "UNDERSTAND",
  "taskQuestionIds": [
    1334,29393,192993,40000
  ]
  "nextNodeId": 2233
}

{
  "name": "分派节点",  
  "description": "分派节点描述",
  "type": "DISPATCH",
  "checkOtherSkill": true,
}

{
  "name": "处理节点",  
  "description": "处理节点描述",
  "type": "PROCESS",
  "processor": {
    "type": "SIMPLE", // SIMPLE, WEBAPI, FAAS
    "content": {
      "ops": [
        {
          "condition": "param1 >= 3",
          "evals": [
            "param2 = 8",
            "param3 = param1"
          ]
        }
      ]
    },
  },
  "nextNodeId": 1222
}

{
  "name": "回复节点",  
  "description": "回复节点描述",
  "type": "RESPONSE",
  "response": {
    ... // 同回复消息
  },
  "nextNodeId": 1222
}

响应消息

{
  "created": {
    "id": 2233, // nodeId
    "processor": { // 如果是处理节点
      "id": 1993
    },
    "response": { // 如果是回复节点
      "id": 9394,
      "answerIds": [...]
    }
 }
}

4.10.8 查看节点#

GET /scenes/<sceneId>/nodes/<nodeId>

请求消息

无

响应消息

根据不同的节点类型，会返回不同的内容。

仅以入口节点为例：

{
  "id": 19393, // nodeId
  "name": "入口节点",  
  "description": "入口描述",
  "type": "ENTRY",
  "taskQuestionIds": [
    1334,29393,192993,40000
  ],
  "nextNodeId": 2233
}

4.10.9 修改节点#

PATCH /scenes/<sceneId>/nodes/<nodeId>

修改场景中的某个节点。

请求消息

根据 nodeId 的类型不同，其可修改字段不同。

节点类型	可修改字段
入口节点	`name`, `description`, `taskQuestionIds`，`nextNodeId`
理解节点	`name`, `description`, `taskQuestionIds`, `nextNodeId`
分派节点	`name`, `description`, `checkOtherSkill`
处理节点	`name`, `description`, `nextNodeId`
回复节点	`name`, `description`, `nextNodeId`

所有字段都是可选项，字段的具体说明请参见“创建节点”。

响应消息

{
  "updated": {
    "id": 12333 // nodeId
  }
}

4.10.10 删除节点#

DELETE /scenes/<sceneId>/nodes/<nodeId>

删除当前节点。

如果是分派节点，需要删除其下的所有分派分支。

如果是回复节点，需要删除其下的回复。

如果有其它节点/分派分支的Next节点指向当前要删除的节点，需要把其它节点的 nextNodeId 更改为 0。

请求消息

无

响应消息

{
  "deleted": {
    "id": 1233,
    "branchIds": [ // 如果是分派节点，有此项
      3000, 3002
    ],
    "processor": { // 如果是处理节点
      "id": 1993
    },
    "response": { // 如果是回复节点
      "id": 9394,
      "answerIds": [...]
    }
  }
}

4.10.11 创建分派节点分支#

POST /scenes/<sceneId>/nodes/<nodeId>/branches

nodeId 节点必须是分派节点。

请求消息

参数	类型	必选	说明
condition	String	是	跳转条件
nextNodeId	Integer	是	跳转到的节点 ID
nextSceneSkillId	Integer	是	跳转到的场景技能 ID

condition 跳转条件总是针对变量进行比较，如果满足条件，则进行跳转。具体请参见 “基础概念-比较条件” 一节。

nextNodeId 和 nextSceneSkillId 表示跳转的位置。二者必须同时指定，且不能同时不为 0。

当 nextNodeId 不为 0 时，表示分派到某个节点，此节点必须是本场景中的一个节点
当 nextSceneSkillId 不为 0 时，表示跳转到某个场景技能（是技能ID，而非场景ID），此场景技能必须是同一个机器人绑定的技能，并且具有一个无条件入口节点
当两者都为 0 时，表示跳出当前的场景技能

在一个分派节点下，分支的 order 会按照加入的顺序自动递增（越小的优先级越高），不能在请求消息中指定。如果要修改分支顺序，必须通过 “修改分支顺序” 接口进行修改。

跳转到本场景的另一个节点

{
  "condition": "gloabl.var1 == 15 && slots.fromCity.normValue=\"北京\"",
  "nextNodeId": 233,
  "nextSceneSkillId": 0
}

跳转到另一个场景技能的无条件入口节点

{
  "condition": "gloabl.var1 == 15 && slots.fromCity.normValue=\"北京\"",
  "nextNodeId": 0,
  "nextSceneSkillId": 533
}

跳出此场景

{
  "condition": "gloabl.var1 == 15 && slots.fromCity.normValue=\"北京\"",
  "nextNodeId": 0,
  "nextSceneSkillId": 0
}

响应消息

{
  "created": {
    "id": 2993
  }
}

4.10.12 查看分派节点分支#

GET /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>

请求消息

无

响应消息

{
  "order": 1,
  "condition": "gloabl.var1 == 15 && slots.fromCity.normValue==\"北京\"",
  "nextNodeId": 0,
  "nextSceneSkillId": 533
}

4.10.13 修改分派节点分支#

PATCH /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>

不允许直接修改 order，需要使用 “修改分支顺序” 接口来一起修改所有分支的顺序。

除 order 外，其余属性都可以通过此接口修改。

请求消息

可修改字段：condition, nextNodeId, nextSceneSkillId

nextNodeId 和 nextSceneSkillId 必须同时指定，且不能同时不为 0。

所有字段都是可选项，字段的具体说明请参见 “创建分派节点分支”。

响应消息

{
  "updated": {
    "id": 1233
  }
}

4.10.14 修改分派节点分支顺序#

PATCH /scenes/<sceneId>/nodes/<nodeId>/branch_order

请求消息

参数	类型	必选	说明
branches	Array of Integer	是	所有分支的Id

{
  "branches": [19393, 1233, 1233, 9393]
}

约束

branches 中的分支Id必须是此分派节点所属的分支，如果出现非法的分支Id或者不属于此分派节点的分支Id，返回错误
如果分支Id有重复，返回错误
如果此分派节点还有 branches 定义的分支之外的分支Id，返回错误

响应消息

{
  "updated": {
    "id": 1999 // nodeId
  }
}

4.10.15 删除分派节点分支#

DELETE /scenes/<sceneId>/nodes/<nodeId>/branches/<branchId>

删除时，会从其所属的分派节点中删除

请求消息

无

响应消息

{
  "deleted": {
    "id": 1233
  }
}

4.11 技能#

技能相关的接口如下：

接口说明	接口	备注
创建技能	`POST /skills`	返回`skillId`
查看技能	`GET /skills/<skillId>`
修改技能	`PATCH /skills/<skillId>`
删除技能	`DELETE /skills/<skillId>`
获取闲聊技能	`GET /skills/chat`	暂不支持

4.11.1 创建技能#

POST /skills

创建技能，返回skillId，此时需要指定技能类别

请求消息

参数	类型	必选	说明
name	String	是	技能名称，不能重名
description	String	否	技能描述
type	String	是	技能类型 `QABASE`：问答库技能 `KG`：知识图谱技能 `INTENT`：意图技能 `SCENE`：场景技能




bind	Array of Integer	是	绑定内容，根据类型不同而不同
processor	Obejct of Processor	否	后处理步骤，仅 `QABASE`, `KG` 允许有此项

bind 是指此技能绑定的具体内容，根据技能类型不同，绑定的内容也不一样。

技能类型	绑定内容
`QABASE`	问答库技能，只能绑定一个问答目录ID (dirId)
`KG`	知识图谱库技能，只能绑定一个知识图谱ID (kgId)
`INTENT`	意图技能，可以绑定多个意图ID (intentId)
`SCENE`	场景技能，只能绑定一个场景ID (sceneId)

{
  "name": "技能能名称",
  "description": "技能描述",
  "type": "QABASE",
  "bind": [
    1223  
  ],
  "processor": {
    ...
  },
  "chatVars": { // 仅 CHAT 有此项
    "name": "小灵",
    "age": 5,
    "gender": "Female",
  }
}

响应消息

{
  "created": {
    "id": 3333  // skillId
  }
}

4.11.2 查看技能#

GET /skills/<skillId>

请求消息

无

响应消息

{
  "id": 3333, // skillId
  "name": "技能能名称",
  "description": "技能描述",
  "type": "SCENE",
  "bind": [
    1222  
  ],
}

4.11.3 修改技能#

PATCH /skills/<skillId>

请求消息

仅能修改 bind 项，不允许修改 type 项。

响应消息

{
  "updated": {
    "id": 233,
  }
}

4.11.4 删除技能#

DELETE /skills/<skillId>

删除技能本身以及后处理步骤（如有），不删除绑定内容

请求消息

无

响应消息

{
  "deleted" : {
    "id": 3333,
    "processor" : {
      "id": 334
    }
  }
}

4.12 机器人#

接口说明	接口	备注
查询机器人列表	`GET /robots`
创建机器人	`POST /robots`	返回`robotId`
查询机器人	`GET /robots/<robotId>`
修改机器人	`PATCH /robots/<robotId>`
上线机器人发布资源	`PATCH /robots/<robotId>/online`
删除机器人	`DELETE /robots/<robotId>`
创建机器人子资源	`POST /robots/<robotId>/welcome_response`
创建机器人子资源	`POST /robots/<robotId>/fallback_response`
删除机器人子资源	`DELETE /robots/<robotId>/welcome_response`
删除机器人子资源	`DELETE /robots/<robotId>/fallback_response`
创建敏感词回复	`POST /robots/<robotId>/sens_responses`	返回`srId`
查询敏感词回复	`GET /robots/sens_responses/<srId>`
修改敏感词回复	`PATCH /robots/sens_responses/<srdId>`
删除敏感词回复	`DELETE /robots/sen_responses/<srId>`
创建机器人发布资源	`POST /robots/<robotId>/publishs`	返回 `publishId`
查看机器人发布资源	`GET /robots/<robotId>/publishs/<publishId>`
修改机器人发布资源	`PATCH /robots/<robotId>/publishs/<publishId>`
删除机器人发布资源	`DELETE /robots/<robotId>/publishs/<publishId>`

4.12.1 查询机器人列表#

GET /robots

查询本租户下的机器人列表。

请求消息

无

响应消息

robots 中的每个元素，结构和“查看机器人”输出一致。

{
  "robots": [
    {
      ... //robotA
    },
    {
      ... //robotB
    }
  ]
}

4.12.2 创建机器人#

POST /robots

请求消息

参数	类型	必选	说明
name	String	是	机器人名称，一个租户下不能重名
description	String	否	机器人描述
bindSkills	Array of BindSkill	是	绑定的技能列表
welcomeSkillId	Integer	否	开场白场景技能ID, 优先于 `welcomeResposne` 缺省为 0，表示不使用场景技能，此时使用开场白话术
welcomeSkillId	Integer	否	开场白场景技能ID, 优先于 `welcomeResposne` 缺省为 0，表示不使用场景技能，此时使用开场白话术
welcomeResponse	Obejct of Response	否	开场白话术
fallbackResponse	Object of Response	否	兜底话术
sensResponses	Array of SensResponse	否	敏感词及对应话术
correctLexiconId	Integer	否	纠错白名单词典 Id 缺省为 0，表示不使用纠错白名单
correctLexiconId	Integer	否	纠错白名单词典 Id 缺省为 0，表示不使用纠错白名单
stopLexiconId	Integer	否	停用词词典Id 缺省为 0，表示不使用停用词
stopLexiconId	Integer	否	停用词词典Id 缺省为 0，表示不使用停用词
taskForgotRound	Integer	否	任务型技能遗忘轮数，[0-10]，缺省为3
qaScortHigh	Float	是	问答库置信度直接回答阈值
recommendSize	Integer	否	推荐问题最大数量，缺省为10
recommendStart	String	否	推荐问题前置提示语，缺省为空
recommendEnd	String	否	推荐问题后置提示语，缺省为空
preload	Boolean	否	是否预加载机器人，缺省为false，不进行预加载

taskForgotRound

如果任务型技能在“允许跳到其它技能”的情况下跳出了然后并未立即恢复，而是一直在“问答型”技能中，此任务型技能仍然会保持几轮。在超过 taskForgotRound 定义的轮数之后，才真正退出此任务型技能，并清除此技能中保持的变量。

qaScoreHigh, recommendSize, recommnedStart, recommendEnd

当知识库技能的命中问题置信度阈值大于 qaScoreHigh 阈值时，将会直接回答（返回问答对中的答复），否则其返回的是置信度大于 scoreLow (问答库技能置信度下限) 的多个问题组成的“推荐问题列表” (RECOMMNED 类型的答案, 其start,end 分别由 recommendStart和 recommendEnd 确定， menu 为这多个标准问的Id和内容) 。推荐问题数量不超过 recommendSize，同属一个标准问的标准问或者扩展问只取一条，并使用标准问作为输出。推荐问题可以跨问答库技能。

BindSkill 表示绑定的技能机器配置，根据技能种类不同，有不同的配置项。其定义如下：

参数	类型	必选	说明
id	Integer	是	绑定的技能ID
scoreLow	Float	是	各技能的置信度下限
digitNorm	Boolean	否	是否进行数字归一化处理 `true`：进行，`false`（缺省）:不进行
digitNorm	Boolean	否	是否进行数字归一化处理 `true`：进行，`false`（缺省）:不进行
correct	Boolean	否	是否进行智能纠错处理 `true`：进行，`false`（缺省）:不进行
correct	Boolean	否	是否进行智能纠错处理 `true`：进行，`false`（缺省）:不进行

scoreLow

如果某种技能的命中问题的置信度，低于对应类型的置信度下限时，将直接忽略此命中问题。否则会作为候选，参与后续的置信度排序过程。

SensResponse 定义如下：

参数	类型	必选	说明
lexiconId	Integer	是	敏感词词典ID，通过“创建词词典”接口创建的
response	Object of Response	是	敏感词命中时的回复

{
  "name": "RobotA",
  "description": "教育机器人",
  "bindSkills": [
    {
      "id": 19828,
      "scoreLow": 0.4,
      "digitNorm": true
    },
    {
      "id": 29283,
      "scoreLow": 0.4,
    }
  ],
  "welcomeSkillId": 222,
  "welcomeResponse": {
    ... // Response
  },
  "fallbackResponse": {
    ... // Response
  },
  "sensResponses": [
    {
      "lexiconId": 2222, // 敏感词词典, lexiconId
      "response": {
        ... // Response
       }
    }
  ],
  "taskForgotRound": 5,
  "qaScoreHigh": 0.8,
  "recommandStart": "xxx",
  "recommendEnd": "xxx",
  "preload": true
}

响应消息

{
  "created": {
    "id": "1234567890abcdef", // robotId - 16位字符串
    "welcomeResponse": {
      "id": 9393 // responseId
    },
    "fallbackResponse": {
      "id": 223 // responseId
    },
    "sensResponses": [
      {
        "response": {
          "id": 93944, // responseId
          "answers" : [
            { "id": 1000 } // answerId
          ]
        }
      }
    ]
}

4.12.3 查询机器人#

GET /robots/<robotId>

请求参数

参数	类型	必选	说明
detail	Boolean	否	当前查询返回的信息中，是否要展开显示回复相关的内容 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回的信息中，是否要展开显示回复相关的内容 true(缺省): 展开；false: 不展开

示例:

GET .../robots/1233?detail=true

请求消息

无

响应消息

detail 为 true时，会展开 welcomeResponse, fallbackResponse 和 sensResponses 里面的 response,

{
  "id": "1234567890abcdef",
  "name": "RobotA",
  "bindSkills": [
    {
      "id": 19828,
      "scoreLow": 0.4,
      "digitNorm": true
    },
    {
      "id": 29283,
      "scoreLow": 0.4,
      "scoreHigh": 0.8,
      "recommandStart": "xxx",
      "recommendEnd": "xxx"
    }
  ],
  "welcomeResponse": {
    "id": 9822,
    ... // 可能展开
  },
  "fallbackResponse": {
    "id": 2983,
    ... // 可能展开
  },
  "sensResponses": [
    {
      "lexiconId": 1223,
      "response": {
        "id": 1983,
        ... // 可能展开
      }
    }
  ]
}

4.12.4 修改机器人#

PATCH /robots/<robotId>

请求消息

可修改字段 name, description, bindSkills, welcomeSkillId, correctLexiconId, stopLexiconId, taskForgotRound, qaScoreHigh, recommendSize, recommendStart, recommendEnd, preload。

bindSkills 整体进行修改。

当 welcomeSkillId, correctLexiconId, stopLexiconId 为 0 时，表示不使用相应的资源。

当 preload 修改时，需要更新 Consul 中的发布机器人的KV值。

所有字段都是可选项，具体说明请参见“创建机器人”。

修改 welcomeRepsonse, fallbackResponse，使用“修改回复"接口。

修改 sensResponses 使用“修改敏感词回复”接口。

响应消息

{
  "updated" : {
    "id": "1234567890abcdef" // robotId
  }
}

4.12.5 上线机器人发布资源#

PATCH /robots/<robotId>/online

当上线一个新的机器人发布资源时，之前的上线资源会自动下线。

一般都是上线最新的机器人发布资源，但也可以指定历史版本的机器人发布资源，以实现“回退”的功能。

当机器人发布资源ID为空串（"") 时，表示下线当前机器人资源。

上线或下线机器人的时候，需要更新 Consul 中的发布机器人的KV值。

请求消息

参数	类型	必选	说明
publishId	String	是	机器人发布资源ID

{
  "publishId": "fedcba0987654321" // publishId, 16位字符串
}

响应消息

{
  "updated" : {
    "id": "1234567890abcdef", // robotId
    "newPublishId": "fedcba0987654321", // 设置成功的发布资源Id
    "oldPublishId": "", // 被替换的发布资源Id，如果之前没有发布资源，为空串
  }
}

4.12.6 删除机器人#

DELETE /robots/<robotId>

会删除此机器人及其下所有发布机器人资源。绑定技能、开场白场景技能不被删除，但敏感词回复、兜底话术、开场白的简单回复都会删除。

如果此机器人有在线的发布资源，不能被删除。删除在线的机器人，会返回 409 Conflict。

请求消息

无

响应消息

{
  "deleted": {
    "id": "1234567890abcdef", // robotId
    "welcomeResponse": {
      "id": 10993, // responseId
      "answerIds": [
        10001, 10002 // answerId
      ]
    },
    "fallbackResponse" : {
      "id": 193, //responseId
      "answerIds": [...]
    },
    "sensResponses": [
      {
        "id": 2933, // srId
        "response": {
          "id": 93944, // responseId
          "answerIds" : [...]
        }
      }
    ],
    "publishIds": [
      "fedcba0987654321", "fedcba0987654322"
    ]
  }
}

4.12.7 创建机器人子资源#

创建开场白话术：POST /robots/<robotId>/welcome_response

创建兜底话术：POST /robots/<robotId>/fallback_response

使用这些接口来创建机器人的子资源。只有在创建机器人时没有指定这些资源时，才能用这些接口创建，如果已经存在，则返错。

创建话术的接口请求消息和响应消息参见创建回复子资源。

4.12.8 删除机器人子资源#

删除开场白话术：DELETE /robots/<robotId>/welcome_response

删除兜底话术：DELETE /robots/<robotId>/fallback_response

使用这些接口删除机器人的子资源。

删除话术的接口请求消息和响应消息参见删除回复子资源。

4.12.9 创建敏感词回复#

POST /robots/<robotId>/sens_responses

创建敏感词同时，会创建其对应话术。

请求消息

请求消息为一个 SensResponse 结构。

{
  "lexiconId": 1993,
  "response": {
    ... // Response
  }
}

响应消息

{
  "created": {
    "id": 10000,
    "response": {
      "id": 91933,
      "answers": [
        {
          "id": 1000
        }
      ]
    }
  }
}

4.12.10 查询敏感词回复#

GET /robots/<robotId>/sens_responses/<srId>

请求参数

参数	类型	必选	说明
detail	Boolean	否	当前查询返回的信息中，是否要展开显示回复相关的内容 true(缺省): 展开；false: 不展开
detail	Boolean	否	当前查询返回的信息中，是否要展开显示回复相关的内容 true(缺省): 展开；false: 不展开

示例:

GET .../robots/fedcba0987654321/sens_responses/1333?detail=true

请求消息

无

响应消息

detail 为 true时，会展开 response,

{
  "id": 10000,
  "lexiconId": 2993,
  "response": {
    "id": 91933,
    ... // 可能会展开
}

4.12.11 修改敏感词回复#

PATCH /robots/<robotId>/sens_responses/<srId>

只能修改lexiconId

response，使用“修改回复”接口。

请求消息

{
  "lexiconId": 83834
}

响应消息

{
  "updated": {
    "id": 10000
  }
}

4.12.12 删除敏感词回复#

DELETE /robots/<robotId>/sens_responses/<srId>

删除敏感词及其对应话术，删除其所属机器人中的绑定。

请求消息

无

响应消息

{
  "deleted": {
    "id": 10000,
    "response": {
      "id": 91933,
      "answerIds": [
        1000, 1001
      ]
    }
  }
}

4.12.13 创建机器人发布资源#

POST /robots/<robotId>/publishs

请求信息

参数	类型	必选	说明
name	String	是	机器人发布资源名称，一个机器人下不能重名
description	String	否	机器人发布资源描述

{
  "name": "机器人发布资源",
  "description": "机器人发布资源描述",
}

根据 robotId 进行机器人资源包生成，语义模型使用本租户当前选用的模型（可能是基础模型，也可能是训练模型），资源包生成在服务器预先指定的目录下，具体路径在响应消息中返回。

响应消息

由于创建完成后，机器人发布资源会有部分新的字段，因此创建完成后，除了created 字段外，还有一个 publish 字段外，结构同“查看机器人发布资源”时候的输出。

{
  "created": {
    "id": "fedcba0987654321" // pubishId
  },
  "publish": {
    ...
  }
}

4.12.14 查看机器人发布资源#

GET /robots/<robotId>/publishs/<publishId>

请求消息

无

响应消息

{
    "id": "fedcba0987654321", // publishId
    "name": "发布机器人",
    "description": "发布机器人描述",
    "robot": {
      "id": "1234567890abcdef", // robot_id
      "name": "xxxx",
      "description": "xxx"
    },
    "model": {
      ... // 同“查看语义模型”输出，可能是基础模型，也可能是优化模型
    },
    "publishTime": "20200401",
    "packagePath": "robot/1234567890abcdef/fedcba0987654321.robot",
  }
}

4.12.15 修改机器人发布资源#

PATCH /robots/<robotId>/publishs/<publishId>

可修改字段：name, desscription。

所有字段都是可选项，字段的具体说明请参见 “创建机器人发布资源”。

请求信息

{
  "name": "xxxx",
  "description": "xxxxx",
}

响应信息

{
  "updated" : {
    "id": "fedcba0987654321"
  }
}

4.12.16 删除机器人发布资源#

DELETE /robots/<robotId>/publishs/<publishId>

删除时会同时删除在服务器定义的存储路径下的机器人资源包。

如果试图删除当前正处于上线状态的机器人发布资源，会返回 409 Conflict。

请求消息

无

响应消息

{
  "deleted": {
    "id": 939
  }
}

4.13 语义模型#

接口说明	接口	备注
查看系统模型列表	`GET /sys_models`
查看语义模型	`GET /models/<modelId>`	`modelId` 也接受 `baseModelId`
修改启用的语义模型	`PATCH /active_model`
查看启用的语义模型	`GET /active_model`
查看基础模型列表	`GET /base_models`
创建基础模型	`POST /base_models`	返回 `baseModelId`
查看优化模型列表	`GET /base_models/<baseModelId>/models`
创建优化模型	`POST /base_models/<baseModelId>/models`	返回 `modelId`
修改优化模型	`PATCH /base_models/<baseModelId>/models/<modelId>`
删除优化模型	`DELETE /base_mdoels/<baseModelId>/models/<modelId>`

4.13.1 查看系统模型列表#

GET /sys_models

获取系统的所有预置语义模型。这些语义模型可以分配给租户，作为某个租户的基础语义模型。

此接口实际与某个租户无关，因此也不受 X-Tenant-Id HTTP 头的影响。

请求消息

无

响应消息

{
  "sysModels": [
    {
      "id": 1233, // sysModelId
      "name": "finance",
      "description": "金融领域语义模型",
      "modelPath": "relative/path/to/sys_model"
    },
    {
      ...
    }
  ]
}

4.13.2 查看语义模型#

GET /models/<modelId>

查看语义模型，可以查看基础模型或优化模型。

如果是优化模型，那么响应消息中还会包括 baseModel 字段。

请求消息

无

响应消息

基础模型

{
  "id": 9468,
  "sysModelId": 111, // sysModelId
  "name": "finance",
  "description": "金融领域语义模型",
  "modelPath": "relative/path/to/base_model",
  "active": true
}

优化模型

{
  "id": 9468,
  "name": "finance_2",
  "description": "金融领域语义模型-训练模型20200301",
  "modelPath": "relative/path/to/optimize_model",
  "trainedTime": "2019-03-18T10:58:37+08:00",
  "baseModel": {
    "id": 1233, // baseModeId
    "sysModelId": 111, // sysModelId
    "name": "finance",
    "description": "金融领域语义模型",
    "modelPath": "relative/path/to/base_model"
  },
  "active": true
}

4.13.3 修改启用的语义模型#

PATCH /active_model

当租户启用某个语义模型时，会替换之前启用的语义模型。

请求消息

参数	类型	必选	说明
modelId	Integer	是	要启用的语义模型Id

modelId 必须是有效的模型Id，可以是基础模型，也可以是优化模型，注意不能是系统模型Id。

响应消息

{
  "updated": {
    "newModelId": 1222, // modelId or baseModelId
    "oldModelId": 193,  // 被替换的模型Id
  }  
}

4.13.4 查看启用的语义模型#

GET /models/active

查看当前租户启用的语义模型。

请求消息

无

响应消息

{
  ... // 同查看语义模型输出
}

4.13.5 查看基础模型列表#

GET /base_models

获取本租户的所有基础模型。

请求消息

无

响应消息

{
  "baseModels" : [
    {
      "id": 9468, // baseModelId
      "sysModelId": 111, // sysModelId
      "name": "finance",
      "description": "金融领域语义模型",
      "modelPath": "relative/path/to/base_model",  // 模型所在路径
      "active": false
    },
    {
      ...
    }
  ]
}

4.13.6 创建基础模型#

POST /base_models

通过本接口为本租户指定可用的系统模型，也即在本租户中生成对应的基础模型。

暂时不考虑绑定后，修改基础模型的情况。如果已经生成了基础模型，再调用此接口会返回：409 Conflict。

此接口会将第一个模型作为本租户缺省的“启用模型”。

请求消息

参数	类型	必选	说明
sysModelIds	Array of Integer	是	绑定的系统模型Id列表

系统模型Id 从 “查看系统模型列表” 系统接口中获取。

{
  "sysModelIds": [
    111, 112
  ]
}

响应消息

返回本租户对应的系统模型

{
  "created": {
    "ids": [1233, 1234] // baseModelId
  }
}

4.13.7 查看优化模型列表#

GET /base_models/<baseModelId>/models

查看所有通过 baseModelId 指定的基础模型训练出来的优化语义模型。

请求消息

无

响应消息

{
  "models" : [
    {
      "id": 9468,
      "name": "finance_2",
      "description": "金融领域语义模型-训练模型20200301",
      "modelPath": "/relative/path/to/optimize_model",
      "trainedTime": "2019-03-18T10:58:37+08:00",
      "active": false
    },
    {
      ...
    }
  ]
}

4.13.8 创建优化模型#

POST /base_models/<baseModelId>/models

新建一个训练后的语义模型，此语义模型是通过 baseModelId 指定的基础模型训练的。

请求消息

参数	类型	必选	说明
name	String	是	语义模型名称
description	String	否	此语义模型描述
modelPath	String	是	此语义模型所存储的路径，是相对路径
trainedTime	String	是	此模型训练完成的时间

{
  "name": "finance_trained3",
  "description": "金融领域语义模型_训练3",
  "modelPath": "relative/path/to/optimize_model",
  "trainedTime": "2019-03-18T10:58:37+08:00"
}

响应消息

{
  "created": {
    "id": 9468 // modelId
  }
}

4.13.9 修改优化模型#

PATCH /base_models/<baseModelId>/models/<modelId>

请求消息

可修改字段 name, description。

所有字段都是可选项，具体说明请参见“创建优化模型”。

响应消息

{
  "updated": {
    "id": 1233  // modelId
  }
}

4.13.10 删除优化模型#

DELETE /base_models/<baseModelId>/models/<modelId>

只能删除优化模型。

如果优化模型在启用中，禁止删除。如果有上线的机器人资源在使用此优化模型，也禁止删除。删除正在使用中的优化模型，会返回 409 Conflict。

请求消息

无

响应消息

{
  "deleted": {
    "id": 1233 // modelId
  }
}

4.14 导入导出#

接口说明	接口	备注
导出数据	`GET /export`
导入数据	`GET /import`

4.14.1 导出#

GET /export

请求消息

参数	类型	必选	说明
robots	Array of Integer	否	需要导出的机器人资源 Id
skills	Array of Integer	否	需要导出的技能资源 Id
qadirs	Array of Integer	否	需要导出的问答目录资源 Id
scenes	Array of Integer	否	需要导出的场景资源 Id
intents	Array of Integer	否	需要导出的意图资源 Id

{
  "robots": [ 133, 233],
  "skills": [ 1000, 1002],
  "qadirs": [ 203, 33],
  "scenes": [ 1112, 333],
  "intents": [ 302, 9223]
}

响应消息

{
  "tagGroups": [ "xxx", "xxx" ],
  "lexicons": [ {...}, {...} ],

  "robots": [  {...}, {...} ],
  "skills": [ {...}, {...}],
  "qadirs": [  {...}, {...} ],
  "scenes": [  {...}, {...} ],
  "intents": [  {...}, {...} ]
}
}

4.14.2 导入#

GET /import

请求消息

JSON 格式，同导出数据格式

响应消息

{
  "result": "ok"
}