智能客服对话平台ICS

    开放接口总览

    使用说明

    前言

    1.API的作用

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

    1. 角色说明

    NGD服务分为管理端和服务端。

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

    服务端: 最终用于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

    注:本文请求地址中的versionId默认都为1


    请求返回值

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

    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. 对接线上用户对话服务。

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

    图片

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

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

    图片

    接口清单

    image2020-4-26_15-56-28.png

    NGD的开放接口从业务上来看主要分为四类,分别是平台管理、统计分析、会话服务和NLU服务,其中前两类主要是针对管理端(因此地址一般为/open),后两类主要针对于服务端(因此地址一般为/core)。具体的接口清单如下:

    平台管理:待开放

    统计分析:待开放

    会话服务:https://cloud.baidu.com/doc/ICS/s/gjzjkefm0

    NLU服务:待开放

    上一篇
    常见问题
    下一篇
    接口清单