测试规则标签
概述
调用接口,可输入一组模拟通话数据,测试当前租户机器人下已保存、已启用的自定义规则标签(V2),返回本次命中的标签 ID 和名称。
本接口只执行规则匹配,不调用模型、不发起通话,也不保存测试样本、正式会话或 ES 记录。只有父标签和对应子规则均启用时,该子规则才参与测试;同一标签下任意一条启用子规则满足即可命中该标签。
URL
https://aiob-open.baidu.com/api/v1/robot/label/rule/test
HTTP Method
POST
请求参数
HEADER
| 参数名称 | 是否必须 | 说明 | 示例 |
|---|---|---|---|
| Authorization | 是 | 参考“生成认证Token”文档获取完整的 OpenAPI Token,原样传入,不加 Bearer 前缀。 | cc-api-auth-v2/your_token |
| Content-Type | 是 | 请求体采用 JSON 格式。 | application/json |
PARAM
以下参数通过 JSON 请求体传入。robotId 必填,其他模拟量按该机器人全部启用标签下的启用子规则所用条件填写,无需固定提交全部字段。
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| robotId | 是 | String | 当前租户的机器人 ID,不能为空。支持草稿或线上机器人,按传入 ID 的实际已保存配置测试,不自动切换机器人版本。 | "11111111-1111-4111-8111-111111111111" |
| talkingTimeLen | 有通话时长条件时必填 | int | 模拟通话时长,单位为秒,范围 0~2147483647。不会从 recordInfo 自动推导。 | 60 |
| talkingTurn | 有机器人回复次数条件时需提供,可由文本推导 | int | 模拟机器人回复次数,范围 0~2147483647。显式值优先,包括 0;未传或传 null 时可由 recordInfo 推导。 | 2 |
| voiceTalkingTurn | 有用户回复次数条件时需提供,可由文本推导 | int | 模拟用户回复次数,范围 0~2147483647。显式值优先,包括 0;未传或传 null 时可由 recordInfo 推导。 | 1 |
| recordInfo | 否 | String | 模拟对话文本,仅用于推导未提供的双方回复次数。按每行开头的角色前缀及冒号识别,具体规则见下方说明。 | "AI:您好\n用户:你好" |
| callTimes | 有拨打次数条件时必填 | long | 模拟拨打次数,范围 0~9223372036854775807。直接传 JSON 整数。 | 1 |
| connectedTimes | 有接通次数条件时必填 | int | 模拟接通次数,范围 0~2147483647。 | 1 |
| endType | 有接听状态或最终通话状态条件时必填 | int | 模拟接听状态:0 未接听,1 已接听。最终通话状态条件在 endType=1 时按 answered 匹配。 | 1 |
| endTypeReason | 有最终通话状态条件且 endType=0 时必填 | String | 未接听原因编码,如 linebusy(用户忙)、nooneheard(无人接听);兼容对应呼叫侧编码,如 line-busy、no-one-heard。不要传中文描述、数字分类值或 answered。endType=1 时无需填写。 | "linebusy" |
| hangup | 有挂断方条件时必填 | int | 模拟挂断方:0 机器人挂断,1 管理员挂断,2 用户挂断,3 振铃挂断。 | 2 |
| transResult | 有转人工结果条件时必填 | int | 模拟转人工结果:0 未发起,1 成功,-1 失败;也兼容 2 主动放弃、3 队列超时、5 队列溢出,匹配时均按失败处理。不支持 4 或其他值。 | 1 |
| collectInfo | 有采集内容条件时必填 | array<object> |
模拟采集结果。须与 customVariables 一起显式提供,不使用的一组传 []。数组元素参数见下表。 | [{"key":"购买情况","value":"已购"}] |
| customVariables | 有采集内容条件时必填 | array<object> |
模拟自定义变量。须与 collectInfo 一起显式提供,不使用的一组传 []。数组元素参数同 collectInfo。 | [] |
| tagExtractInfo | 有模型标签条件时必填 | array<object> |
手动提供模拟模型标签结果,不会根据 recordInfo 调用模型生成;没有结果时可显式传 []。数组元素参数见下表。 | [{"key":"意向","value":["高"]}] |
collectInfo、customVariables 数组中的对象参数:
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| key | 提交对象时必填 | String | 采集项或变量名称,须为非空白内容。当前规则按两组输入合并后的 value 匹配,不按 key 区分字段。 | "购买情况" |
| value | 提交对象时必填 | String | 该项的模拟值,可为空字符串,不能为 null。 | "已购" |
tagExtractInfo 数组中的对象参数:
| 参数名称 | 是否必须 | 参数类型 | 说明 | 示例 |
|---|---|---|---|---|
| key | 提交对象时必填 | String | 模型标签名称,须为非空白内容。与 value 中的每个标签值组合参与匹配。 | "意向" |
| value | 提交对象时必填 | array<string> |
该模型标签的模拟值列表,单值也按数组提交。可为 [],数组元素可为空字符串,但不能为 null。 | ["高"] |
模型标签测试只需填写 key 和 value,无需填写 valueType。例如 key="意向"、value=["高"],匹配时组合为“意向:高”,对应已保存模型标签条件中的同名比较值;不要在 value 中重复填写标签名。
没有模型标签结果时,建议直接传 tagExtractInfo=[]。如果 tagExtractInfo 非空,但所有对象的 value 都为 [],当前实现会将模型标签条件判为不命中,IN、NOT_IN 均如此;这与整体传 [] 的匹配行为不同。标签最终是否命中仍按子规则的 AND、OR 及同一标签下多条子规则的关系决定。
说明:
- 测试范围由 Authorization 所属租户确定。机器人不存在、已删除或不属于当前租户时,测试失败。测试读取传入 robotId 下所有启用标签的启用子规则,无需传标签 id、version 或临时 rules。
- 必需输入按所有参与测试的子规则统一检查,不能只为预期命中的某一个标签提供数据。即使某条子规则使用 OR,或某个标签存在多条可选子规则,相关条件所需的模拟量也须补齐;禁用标签和禁用子规则不增加输入要求。
- 不传和传 null 都表示未提供,不能用 null 代替 0 或 []。0 是有效数值输入;[] 是明确提供空集合的有效输入,仍由已保存规则决定是否命中,可能满足 NOT_IN 条件。例如已保存的模型条件为 NOT_IN ["意向:高"] 时,tagExtractInfo=[] 会满足该条件。缺少必需模拟量时返回业务码 4007509,并在 msg 中提示缺失字段。
- recordInfo 按行首角色前缀统计回复次数,机器人侧识别 AI、机器人、坐席,用户侧识别 用户、客户、USER、user,角色后支持英文冒号或中文冒号。角色写法区分大小写。只补充未显式提供的次数,不覆盖已有值。一旦识别到至少一行,未出现一方且未显式提供的次数会补为 0;例如只识别到一行“AI:您好”时,未显式提供的 talkingTurn、voiceTalkingTurn 分别补为 1、0。完全没有识别到角色行时,不自动补 0,缺少的必需次数仍会报缺失输入。文本不会自动产生通话时长、挂断方、接听状态、采集结果或模型标签。
- collectInfo、customVariables、tagExtractInfo 的每个元素须为非 null 对象。已提交的数值模拟量和这三组集合对象,即使未被当前启用规则使用,也会校验取值或结构。
- recordInfo 的长度,加上 collectInfo、customVariables、tagExtractInfo 中全部 key 和 value 的字符串长度,总计默认不超过 20000;实际以当前部署配置为准。该限制按字符串长度计算,不按 JSON 请求体字节数计算。
- 采集内容匹配合并 collectInfo 和 customVariables 的 value;模型标签匹配使用“标签名:标签值”。当前多值匹配会将英文逗号作为分隔符,拆分后按完整项、区分大小写比较,不做子串模糊匹配。
- 正常完成但没有命中时返回成功和空的 customTagList;机器人没有启用标签,或启用标签没有启用子规则时也不会命中。配置读取或规则计算失败时返回错误,不以成功空列表代替失败。
响应参数
公共响应字段:
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| requestId | string | 请求标识,用于定位请求。 |
| time | long | 响应时间戳,单位为毫秒。 |
| code | int | 业务结果码,200 表示成功。 |
| msg | string | 处理结果说明;缺少必需模拟量时提示缺失字段。 |
| data | object | 本次规则标签测试结果,字段见下表。 |
data 字段:
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| customTagList | array<object> |
本次命中的标签列表,没有命中时为空数组。仅返回命中的标签,不返回未命中标签或逐条子规则的判断明细。 |
命中标签对象字段(customTagList 中的每个元素):
| 字段名称 | 数据类型 | 说明 |
|---|---|---|
| id | string | 命中的标签 ID,不是子规则 ID。 |
| tag | string | 命中的标签名称。 |
请求示例
1POST https://aiob-open.baidu.com/api/v1/robot/label/rule/test
1{
2 "robotId": "11111111-1111-4111-8111-111111111111",
3 "talkingTimeLen": 60
4}
本例假设该机器人参与测试的启用规则只使用通话时长条件,且已保存启用标签“通话时长达标”,其启用子规则条件为“通话时长不少于 30 秒”。模拟时长为 60 秒,因此命中该标签。如实际还有其他启用条件,须同时补齐相应模拟量。robotId 和请求头中的 your_token 均须替换为实际值。
返回示例
1{
2 "requestId": "example-request-id",
3 "time": 1794787200000,
4 "code": 200,
5 "msg": "OK",
6 "data": {
7 "customTagList": [
8 {
9 "id": "22222222-2222-4222-8222-222222222222",
10 "tag": "通话时长达标"
11 }
12 ]
13 }
14}
评价此篇文章
