使用说明

前言

1.API的作用

API是UNIT企业版开放能力的基础，借助API可以极大地节省人力成本，提高效率，用更高效的方式完成对UNIT企业版数据资源的管控。对于开发者来说，使用 API 完成一些重复性强的工作可以极大地节约时间和精力；除此之外，API还有便于组合能力、便于自动化、扩展性强等优点。 本文介绍了管理端开放接口的鉴权参数、API请求结构和参数、数据返回结构和参数以及各个模块之间的关系。

2. 角色说明

UNIT企业版服务分为管理端和服务端。

管理端: 用于内部运营使用。管理端数据可以发布推向服务端

服务端: 最终用于C端用户查询使用

开放能力接口范围定义: /open 开头的都是管理端；/core 开头的是服务端；

注意: 管理端和服务端一般使用不同的端口，如果服务端的开放能力接口(/core开头)需要查询管理端数据，可以将url中的ip和port换成管理端的值

请求鉴权

开放能力API调用时，依然需要在HTTP请求的header中加上Authorization字段，值为与Agent相匹配的token。如下：

key	value
Authorization	NGD {token}

Api的地址格式为：{IP}:{PORT}/open/v{versionId}/{model}" 以ip地址为127.0.0.1，端口为8600，FAQ标准问创建地址为例，API的访问地址地址为：127.0.0.1:8600/open/v1/faq/standard/create

/open 开头的使用域名：openapi-ngd.baidu.com，/core 开头的域名地址为：api-ngd.baidu.com

注1：本文请求地址中的未明确写明版本的，versionId默认都为1，其他按照path中的为准

注2：开放接口服务目前默认关闭，有使用需求的用户可以填写咨询单，备注信息注明“开通开放接口使用”

请求返回值

返回值的格式分为请求正确与请求错误两种：

1、请求正确返回值：

参数名	类型	父节点	备注
code	int		HTTP状态码（请求正确则为200）
time	long		时间
msg	string		状态信息
data	T		返回数据

2、请求错误返回值：

参数名	类型	父节点	备注
code	int		错误状态码
requestId	string		请求ID
msg	string		状态信息
tip	string		提示

状态码清单

OPEN API调用基础状态（100）

状态编号	说明
200	请求成功
100001	Agent无API访问权限
100002	Agent访问频率超出限制
100003	SDK版本与服务器版本不匹配
100004	请求参数格式错误
100005	已存在同名内容
100006	数据版本不一致
100999	处理失败

授权错误状态（101）

状态编号	说明
101001	token错误
101002	无权限，访问被拒绝
101003	没有相关操作权限

FAQ&闲聊（102）

状态编号	说明
102001	一个渠道最多只能配置一条答案
102002	已存在相似问题
102003	相同的答案下有多个标准问
102004	已存在相似的标准问
102005	已有其他用户正在对该问题进行编辑
102006	编辑的数据已被删除
102007	问题不存在或无操作权限
102008	问题版本不一致
102009	当前问法是问答标准问，无法加入问答不响应问题中

目录（103）

状态编号	说明
103001	同一目录下存在相同名称
103002	目录结构已变更，请重新操作
103003	目录不存在
103004	已有其他用户正在修改此目录
103005	目录列表数据版本不一致
103006	目录层级超出限制

渠道（104）

状态编号	说明
104001	同名的渠道已存在
104002	渠道数据版本不一致
104003	渠道不存在
104004	渠道在线应用中，请下线后重试

文档库（105）

状态编号	说明
105001	文档不存在或无权限
105002	相同目录下，不允许同名线上文档
105003	已有其他用户正在对该文档进行编辑
105004	文档内容未变化，请修改后再提交
105005	线上文档数据版本不一致，请重试
105006	线上文档正在被编辑，禁止删除操作
105007	文档正在被编辑，禁止移动
105008	文档不存在或内容为空

规则模板（106）

注：意图和问答中均可能使用到规则模板

状态编号	说明
106001	模板不合法
106002	"|"两边不能为空
106003	W:a-b中a和b范围为[0,20]
106004	W:a-b片段中，a<=b
106005	字符串只支持汉字、字母、数字、下划线和中划线
106006	实体ID不存在
106007	关键词/规则不符合规范
106008	插入失败
106009	更新失败
106010	删除失败
106011	词库ID不存在
106012	模板的左右中括号不匹配
106013	模版的“|”不可以嵌套，[[aa|cc]|bb]不合法
106014	中括号中按“|”分割后，特殊符号@、¥、W必须处在开头的位置
106015	[]中间不能为空
106016	当前已存在相同模版
106017	其它已存在相同模版
106018	系统意图下已存在相同模版
106019	?左边不能为空
106020	模版不能超过140个字符
106021	FAQ不存在
106022	模板产生的组合太复杂

意图（107）

状态编号	说明
107001	同名示例已存在
107002	同名的意图ID已存在
107003	问题长度过长
107004	问题不存在
107005	意图不存在
107006	问题必须为列表结构
107007	非法意图ID
107008	系统意图ID不存在
107009	该实体类型已经存在
107010	每个意图别名不超过10个字符
107011	每个意图最多包含5个别名
107012	创建别名失败
107013	意图别名已存在
107014	意图别名只支持中文、英文、数字
107015	已经有意图使用过该别名
107016	意图名称不能为空且不超过20个字符
107017	意图名称仅支持中英文、数字和下划线，且不能以数字开头
107018	用户意图不能与系统意图名称重复
107019	同名的意图名称已存在
107020	每个意图描述不超过20个字符
107021	意图示例不能超过140个字符
107022	Agent下已经存在相同的意图示例

审核相关（108）

状态编号	说明
108001	已在审核流程中，无法操作
108002	已有其他用户正在操作

总时序图

API分为两类：

1. 管理端服务。主要用于数据接入和管理。
2. 对接线上用户对话服务。

本文主要介绍管理端的开放服务。下图显示的是管理端开放服务在UNIT企业版系统中的范围和作用。

渠道和目录是基础资源，先创建这两个基础资源，才可以继续操作FAQ和文档库。FAQ标准问中用到了渠道和目录；文档库中使用了目录资源；闲聊中未使用这两个资源，可直接进行操作。

备注：该文档中展示了core/query接口，具体接口信息请参见core/query文档。

接口清单

UNIT企业版（enterprise）的开放接口从业务上来看主要分为四类，分别是平台管理、统计分析、会话服务和NLU服务，其中前两类主要是针对管理端（因此地址一般为/open），后两类主要针对于服务端（因此地址一般为/core）。