全部产品

API使用

更新时间:2017-08-14 15:46:35   分享:   

1. 问答服务API

​ 问答服务的调用采用Restful API方式,服务内部不保存状态,所以调用和调用之间相互独立。调用API需要校验权限,详细说明见https://help.aliyun.com/document_detail/50410.html

​ 问答服务的输入为目前与用户对话的内容,输出是与输入最匹配的三个知识点,默认第一位最匹配的。

注意:调用问答服务前,知识库必须先发布,可以在管控台点击“发布”按钮或调用 single:online 接口发布。
服务提供方式
协议 URL 方法 参数
HTTPS nlsapi.aliyun.com/qas POST body中的json字符串
请求示例
  1. {
  2. "version": "2.0",
  3. "app_key": "nui-abcefghi",
  4. "question": "你是谁?",
  5. "optional": {"domains":"theme1;theme2;theme3","top":3}
  6. }
请求参数说明
参数 类型 是否必须 说明
version String 协议版本号,必须是2.0
app_key String 创建项目时返回的appId,加上”nui-“前缀
question String 问题
optional/domains String 主题列表,多个主题用分号隔开。如果设置了主题,就从这些主题中匹配答案,否则就从该用户的全部知识库匹配答案
optional/top Integer 返回答案数量,默认3个
返回结果示例
  1. {
  2. "id": "921a3c8ac36c4df39dd714dd52344a53",
  3. "success": true,
  4. "error_code": "",
  5. "error_message": "",
  6. "answers": [
  7. {
  8. "question": "",
  9. "answer": "",
  10. "score": "",
  11. "domain": "",
  12. "optional": {}
  13. },
  14. {
  15. "question": "",
  16. "answer": "",
  17. "score": "",
  18. "domain": "",
  19. "optional": {}
  20. },
  21. {
  22. "question": "",
  23. "answer": "",
  24. "score": "",
  25. "domain": "",
  26. "optional": {}
  27. }
  28. ]
  29. }
返回参数说明
参数 类型 是否必须 说明
id String 请求id
success Boolean 请求是否处理成功
error_code String 如果失败,对应的错误码
error_message String 错误信息
answers[]/question String 知识库中匹配到的问题
answers[]/answer String 知识库中匹配到的答案
answers[]/score Float 该答案对应的得分(0-1.0之间),分越高,答案越准确
answers[]/domain String 该条答案所在的主题
answers[]/optional Object 附加数据,不同的业务定义自己的数据格式

2. 知识库管理API

2.1 通用接口

服务提供方式

协议 URL 方法 参数
HTTPS nlsapi.aliyun.com/manage/qas POST body中为json字符串,query中需要一个action参数

请求参数说明

参数名 类型 示例 备注
action String projects:list 全小写,在query中,https://nlsapi.aliyun.com/manage/qas?action=projects:list
String {“offset”:0, “pageSize”:10} 在body中,action对应的参数组

返回结果为json格式,所有接口返回结果格式一致,唯一区别为data里面的内容。

参数 类型 是否必须 说明
requestId String 唯一请求id
resultCode Integer 错误码
resultMessage String 返回信息
data Object 每个业务的返回数据

错误码为调用返回的resultCode,具体数值如下:

错误码 说明
0 成功
1 登录超时
2 输入参数错误
3 服务器内部错误
4 项目名重复
5 项目个数达到最大
6 资源不存在
100 token错误

2.2 具体调用参数说明

2.2.1 创建项目

Action: projects:create

请求参数说明

参数 类型 是否必须 说明
name String 项目名,最大长度为40
description String 项目描述,最大长度为160

请求示例

  1. {
  2. "name":"测试项目",
  3. "description":"这是一个测试项目"
  4. }

返回结果

  1. {
  2. "requestId": "xxxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "id": 1,
  7. "name": "测试项目",
  8. "description": "这是一个测试项目",
  9. "appId": "wdhlqi9a",
  10. "createTime": "2010-11-10 13:46:00"
  11. }
  12. }

返回结果说明

参数 类型 是否必须 说明
id Long 项目id
name String 项目名
description String 项目描述
appId String 项目appId,加上”nui-“前缀即app key
createTime String 项目创建时间
2.2.2 列出项目

Action: projects:list

请求参数:

参数 类型 是否必须 说明
offset Integer 从第几个项目开始列出
pageSize Integer 每页个数

请求示例:

  1. {
  2. "offset":0,
  3. "pageSize":10
  4. }

返回结果:

  1. {
  2. "requestId": "xxxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "total": 100,
  7. "offset": 0,
  8. "pageSize": 10,
  9. "items": [
  10. {
  11. "id": 1,
  12. "name": "test1",
  13. "description": "test1 desc text",
  14. "appId": "wdhlqi9a",
  15. "createTime": "2010-11-10 13:46:00"
  16. },
  17. {
  18. "id": 2,
  19. "name": "test2",
  20. "description": "test2 desc text",
  21. "appId": "wdhlqi9a",
  22. "createTime": "2010-11-10 13:46:00"
  23. }
  24. ]
  25. }
  26. }

返回结果说明

参数 类型 是否必须 说明
id Long 项目id
name String 项目名
description String 项目描述
appId String 项目appId
createTime String 创建时间
total Integer 项目总数
2.2.3 更新项目

Action: projects:update

请求参数:

参数 类型 是否必须 说明
id Long 项目id
name String 项目名,最大长度40
description String 项目描述,最大长度160

请求示例:

  1. {
  2. "id":1,
  3. "name":"test",
  4. "description":"test description"
  5. }
  1. {
  2. "requestId": "xxxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "id": 1,
  7. "name": "test1",
  8. "description": "test1 desc text",
  9. "appId": "wdhlqi9a",
  10. "createTime": "2010-11-10 13:46:00"
  11. }
  12. }

返回结果说明:

参数 类型 是否必须 说明
id Long 项目id
name String 项目名
description String 项目描述
appId String 项目appId
createTime String 创建时间
2.2.4 删除项目

Action: projects:delete

注:该操作会删除项目相关的所有信息,包括主题、知识点等,请谨慎操作。

请求参数:

参数 类型 是否必须 说明
id Long 项目id

请求示例:

  1. {
  2. "id":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":""
  6. }
2.2.5 获得项目详细信息

Action: projects:get

请求参数:

参数 类型 是否必须 说明
id Long 项目id

请求示例:

  1. {
  2. "id":1
  3. }

返回结果:

  1. {
  2. "requestId": "xxxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "id": 1,
  7. "name": "测试项目",
  8. "description": "这是一个测试项目",
  9. "appId": "wdhlqi9a",
  10. "createTime": "2010-11-10 13:46:00"
  11. }
  12. }

返回结果说明:

参数 类型 是否必须 说明
id Long 项目id
name String 项目名
description String 项目描述
appId String 项目appId
createTime String 创建时间
2.2.6 创建主题

Action: theme:create

请求参数:

参数 类型 是否必须 说明
name String 主题名,最大长度30
description String 描述,最大长度50
projectId Long 项目id

请求示例:

  1. {
  2. "name":"test",
  3. "description":"desc",
  4. "projectId":1
  5. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xx",
  3. "resultCode":"0",
  4. "resultMessage":"OK",
  5. "data": {
  6. "id":1,
  7. "name":"test",
  8. "description":"desc",
  9. "projectId":1
  10. }
  11. }

返回结果说明

参数 类型 是否必须 说明
id Long 主题id
name String 主题名称
description String 主题描述
projectId Long 项目id
2.2.7 列出主题

Action: theme:list

请求参数:

参数 类型 是否必须 说明
offset Integer 从第几个主题开始列出
pageSize Integer 每页个数
projectId Long 项目id

请求示例:

  1. {
  2. "offset":0,
  3. "pageSize":10,
  4. "projectId":1
  5. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":{
  6. "total":100,
  7. "offset":0,
  8. "pageSize":10,
  9. "items":[
  10. {
  11. "id":1,
  12. "name":"test1",
  13. "description":"desc1",
  14. "projectId":1
  15. },
  16. {
  17. "id":2,
  18. "name":"test2",
  19. "description":"desc2",
  20. "projectId":1
  21. }
  22. ]
  23. }
  24. }

返回结果说明:

参数 类型 是否必须 说明
id Long 主题id
name String 主题名称
description String 主题描述
projectId Long 项目id
total Integer 总主题数
2.2.8 更新主题

Action: theme:update

请求参数:

参数 类型 是否必须 说明
name String 主题名,最大长度30
description String 描述,最大长度50
projectId Long 项目id
id Long 主题id

请求示例:

  1. {
  2. "id":1,
  3. "name":"test",
  4. "description":"desc1",
  5. "projectId":1
  6. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xx",
  3. "resultCode":"0",
  4. "resultMessage":"OK",
  5. "data": {
  6. "id":1,
  7. "name":"test",
  8. "description":"desc",
  9. "projectId":1
  10. }
  11. }

返回结果说明

参数 类型 是否必须 说明
id Long 主题id
name String 主题名称
description String 主题描述
projectId Long 项目id
2.2.9 删除主题

Action: theme:delete

请求参数:

参数 类型 是否必须 说明
id Long 主题id
projectId Long 项目id

请求示例:

  1. {
  2. "id":1,
  3. "projectId":1
  4. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":""
  6. }
2.2.10 获得主题详细信息

Action: theme:get

请求参数:

参数 类型 是否必须 说明
id Long 主题id

请求示例:

  1. {
  2. "id":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xx",
  3. "resultCode":"0",
  4. "resultMessage":"OK",
  5. "data": {
  6. "id":1,
  7. "name":"test",
  8. "description":"desc",
  9. "projectId":1
  10. }
  11. }

返回结果说明

参数 类型 是否必须 说明
id Long 主题id
name String 主题名称
description String 主题描述
projectId Long 项目id
2.2.11 创建知识点

注:一个知识点包含多个问题和一个答案。每个问题为一个json object类型,其中question这个key为必选项,其他字段可由用户按需定制。answer为字符串类型,内容由用户自定义,问答服务不对answer做任何处理,原样返回。

Action: single:create

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id
themeId Long 主题id
body String 知识点内容,json格式字符串
note String 知识点描述

请求示例:

  1. {
  2. "projectId":1,
  3. "themeId":1,
  4. "body":{
  5. "questions":[
  6. {"question":"问题1","key1":"value1", ...},
  7. {"question":"问题2"}
  8. ],
  9. "answer":"答案"
  10. },
  11. "note":"这是一个知识点"
  12. }

返回结果:

  1. {
  2. "requestId": "xxxx-xxx-xxxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "message": {
  7. "id": 1234,
  8. "themeId": 1,
  9. "themeName": "主题1",
  10. "body": {
  11. "questions": [
  12. {"question": "问题1", "key1":"value1", ...},
  13. {"question": "问题2"}
  14. ],
  15. "answer": "答案"
  16. },
  17. "note": ""
  18. },
  19. "exists": null,
  20. "sensitive": null
  21. }
  22. }

返回结果说明:

参数 类型 是否必须 说明
message String 知识点信息
exists String 已经存在的问题,json数组
sensitive String 包含敏感词的问题,json数组

message 说明

参数 类型 是否必须 说明
id Long 知识点id
themeId Long 主题id
themeName String 主题名
body String 知识点内容,json格式
note String 知识点描述
2.2.12 列出知识点

Action: single:list

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id
themeId Long 主题id
offset Integer 从第几个知识点开始列出
pageSize Integer 每页数量

请求示例:

  1. {
  2. "projectId":1,
  3. "themeId":1,
  4. "offset":0,
  5. "pageSize":10
  6. }

返回结果:

  1. {
  2. "requestId": "xxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "total":10000,
  7. "offset":0,
  8. "pageSize":10,
  9. "items":[
  10. {
  11. "id": 1,
  12. "themeId":1,
  13. "themeName": "主题名",
  14. "body": {
  15. "questions": [
  16. {"question": "问题1"},
  17. {"question": "问题2"}
  18. ],
  19. "answer": "答案",
  20. }
  21. }
  22. ]
  23. }
  24. }

返回结果说明:

参数 类型 是否必须 说明
id Long 知识点id
themeId Long 主题id
themeName String 主题名
body String 知识点内容,json格式
note String 知识点描述
total Integer 总知识点数
2.2.13 更新知识点

Action: single:update

请求参数:

参数 类型 是否必须 说明
id Long 知识点id
body String 知识点内容,json字符串
note String 知识点描述

请求示例:

  1. {
  2. "id":1,
  3. "note":"这是一个知识点",
  4. "body":{
  5. "questions":[
  6. {"question":"问题1"},
  7. {"question":"问题2"}
  8. ],
  9. "answer":"答案"
  10. }
  11. }

返回结果:

  1. {
  2. "requestId": "xxxx-xxx-xxxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "message": {
  7. "id": 1234,
  8. "themeId": 1,
  9. "themeName": "主题1",
  10. "body": {
  11. "questions": [
  12. {"question": "问题1"},
  13. {"question": "问题2"}
  14. ],
  15. "answer": "答案"
  16. },
  17. "note": ""
  18. },
  19. "exists": null,
  20. "sensitive": null
  21. }
  22. }

返回结果说明:

参数 类型 是否必须 说明
message String 知识点信息
exists String 已经存在的问题,json数组
sensitive String 包含敏感词的问题,json数组

message 说明

参数 类型 是否必须 说明
id Long 知识点id
themeId Long 主题id
themeName String 主题名
body String 知识点内容,json格式
note String 知识点描述
2.2.14 删除知识点

Action: single:delete

请求参数:

参数 类型 是否必须 说明
id Long 知识点id

请求示例:

  1. {
  2. "id":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xx",
  3. "resultCode":"0",
  4. "resultMessage":"OK"
  5. "data": ""
  6. }
2.2.15 获得知识点详细信息

Action: single:get

请求参数:

参数 类型 是否必须 说明
id Integer 知识点id

请求示例:

  1. {
  2. "id":1
  3. }

返回结果:

  1. {
  2. "requestId": "xxxx-xxx-xxx",
  3. "resultCode": 0,
  4. "resultMessage": "OK",
  5. "data": {
  6. "id": 1,
  7. "themeId": 1,
  8. "themeName": "主题名",
  9. "body": {
  10. "questions": {
  11. {"question": "问题1"},
  12. {"question": "问题2"}
  13. },
  14. "answer":"答案"
  15. }
  16. }
  17. }

返回结果说明:

参数 类型 是否必须 说明
id Long 知识点id
themeId Long 主题id
themeName String 主题名
body String 知识点内容,json格式
note String 知识点描述
total Integer 总知识点数
2.2.16 知识库预上线

注:异步接口,需要数分钟时间,跟知识库大小有关,可调用预上线状态接口判断是否成功。

预上线环境相当于一个沙盒,和正式上线环境彼此独立。更新知识库后,为了避免直接上线出错造成不良影响,可以先调用预上线接口,预上线成功后,再调用预上线效果测试接口的问答服务,确认是否和期望的效果一致,然后再正式上线。

Action: single:prepub

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id

请求示例:

  1. {
  2. "projectId":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":""
  6. }
2.2.17 预上线状态检测

Action: single:prepub​:get

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id

请求示例:

  1. {
  2. "projectId":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":"3"
  6. }

返回结果说明:

参数 类型 是否必须 说明
data Integer 上线状态

上线状态说明:

状态码 说明
0 未上线
11 预发上线中
12 预发上线完成
13 预发上线失败
2.2.18 预上线效果测试

Action: single:prepub:qa

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id
domains String 主题列表,多个用分号隔开
question String 问题

请求示例:

  1. {
  2. "projectId":1,
  3. "domains":"themeName1;themeName2",
  4. "question":"你叫什么名字?"
  5. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxxx",
  3. "resultCode":0,
  4. "data":{
  5. "id":"c6c33bb1c4344ebb9eb38d7290fe7b31",
  6. "success":true,
  7. "answers":[
  8. {
  9. "score":0.67396873,
  10. "question":"你叫什么名字",
  11. "answer":"我叫ET啊",
  12. "domain":"faq",
  13. "optional":{
  14. "topic_id":"12345",
  15. "body":"{"question":"知识标题"} "
  16. }
  17. }
  18. ]
  19. }
  20. }

返回结果说明:

参数 类型 是否必须 说明
question String 知识库中匹配到的问题
answer String 知识库中匹配到的答案
score Float 该答案对应的得分(0-1.0之间),分越高,答案越准确
domain String 答案所在的主题
optional/topic_id String 知识点id
optional/body String 原始问题及自定义属性
2.2.19 知识库上线

注:异步接口,需要数分钟时间,跟知识库大小有关,可调用上线状态接口判断是否成功。上线过程中或失败,如调用问答服务,返回的是旧的知识库答案,上线成功后才能返回新的知识库答案。

Action: single:online

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id

请求示例:

  1. {
  2. "projectId":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":""
  6. }
2.2.20 上线状态查询

Action: single:online:get

请求参数:

参数 类型 是否必须 说明
projectId Long 项目id

请求示例:

  1. {
  2. "projectId":1
  3. }

返回结果:

  1. {
  2. "requestId":"xxxx-xxx-xxx",
  3. "resultCode":0,
  4. "resultMessage":"OK",
  5. "data":"3"
  6. }

返回结果说明:

参数 类型 是否必须 说明
data Integer 上线状态

上线状态说明:

状态码 说明
0 未上线
31 正式上线中
32 正式上线完成
33 正式上线失败
本文导读目录
本文导读目录
以上内容是否对您有帮助?