查询多条数据接口调试
1. 简介
1.1 接口简介
通过查询多条数据接口,可以一次查询表单中的多条数据。
1.2 接口版本说明
接口版本 | 更新时间 | 版本说明 |
v1 | 2018.6.21 | 原始接口 |
v2 | 2021.3.11 | 在 v2 的基础上,子表单新增数据 ID 参数,即为子表单中每条子数据新增一个数据 ID(以下简称数据 ID) |
v3 | - | 无 v3 版本 |
v4 | 2022.4.21 | 在 v3 的基础上,新增互联组织部门/成员获取,新增 type 参数类型:
|
v5 | 2022.10.28 | 在 v4 的基础上,接口请求频率由 5 次/秒提升至 30 次/秒; 参数 app_id 和 entry_id 放入 body,接口路由修改为 POST app/entry/data/list。 |
2. 接口调用
该接口的返回数据,始终按照数据 ID 正序排列。
请求地址:https://api.jiandaoyun.com/api/v5/app/entry/data/list
请求频率:30 次/秒
请求方式:POST
请求参数:
参数 | 类型 | 必需 | 说明 |
app_id | String | 是 | 应用ID |
entry_id | String | 是 | 表单ID |
data_id | String | 否 | 上一次查询数据结果的最后一条数据的ID,没有则留空 |
fields | Array | 否 | 需要查询的数据字段 |
filter | JSON | 否 | 数据筛选器 |
limit | Number | 否 | 查询的数据条数,1~100,默认10 |
数据筛选器
查询多条数据接口同时也支持过滤,可通过 filter 参数进行数据过滤。
筛选结构:
参数 | 必需 | 类型 | 说明 |
rel | 是 | String | 筛选组合关系;“and”(满足所有过滤条件), “or”(满足任一过滤条件) |
cond | 是 | [JSON] | 过滤条件列表 |
筛选示例:
{
"rel": "and", // 或者 "or"
"cond": [
// 过滤条件
]
}
过滤条件结构:
参数 | 必需 | 类型 | 说明 |
field | 是 | String | 字段名 |
type | 否 | String | 字段类型 |
method | 是 | String | 过滤方法:
|
value | 否 | Array | 过滤值 |
过滤条件示例:
// 没有参数的过滤条件
{
"field": "_widget_1508400000001",
"type": "text",
"method": "empty"
}
// 有参数的过滤条件
{
"field": "flowState",
"type": "flowstate",
"method": "eq",
"value": [1]
}
目前支持如下字段:
字段类型 | 支持的过滤方式 | 说明 |
flowState | eq,ne | 流程状态,仅对流程表单有效 |
日期时间 | eq,ne,range,empty,not_empty | |
数字 | eq,ne,range,empty,not_empty | |
文本 | eq,ne,in,nin,empty,not_empty | 包括单行文本、下拉框、单选按钮组、流水号 |
手机 | like, verified, unverified, empty, not_empty | verified表示填写了手机号且已验证的值;unverified表示填写了手机号但未验证值 |
其他表单字段(子表单字段除外) | empty,not_empty |
请求示例:
{
"app_id": "59264073a2a60c0c08e20bfb",
"entry_id": "59264073a2a60c0c08e20bfd",
"data_id": "59e9a2fe283ffa7c11b1ddbf",
"limit": 100,
"fields": ["_widget_1508400000001", "_widget_1508400000002", "_widget_1508400000003"],
"filter": {
"rel": "and", // 或者 "or"
"cond": [
{
"field": "flowState",
"type":"flowstate",//字段类型为 flowstate
"method":"eq",//过滤方式为 eq
"value":[0]
} ,
{
"field": "flowState",
"type":"flowstate",//字段类型为 flowstate
"method":"ne",//过滤方式为 ne
"value":[0]
} ,
{
"field": "_widget_1732071387201",
"type": "datetime",//字段类型为 datetime
"method": "range",//过滤方式为 range
"value":["2024-11-20","2024-11-21"]
},
{
"field": "_widget_1732071387201",
"type": "datetime",//字段类型为 datetime
"method": "eq",//过滤方式为 eq
"value":["2024-11-30"]
},
{
"field": "_widget_1732071387201",
"type": "datetime",//字段类型为 datetime
"method": "ne",//过滤方式为 ne
"value":["2024-11-30"]
},
{
"field": "_widget_1732071387201",
"type": "datetime",//字段类型为 datetime
"method": "empty",//过滤方式为 empty
},
{
"field": "_widget_1732071387201",
"type": "datetime",//字段类型为 datetime
"method": "not_empty",//过滤方式为 not_empty
},
{
"field": "_widget_1732071387200",
"type": "number",//字段类型为 number
"method": "eq",//过滤方式为 eq
"value":[1]
},
{
"field": "_widget_1732071387200",
"type": "number",//字段类型为 number
"method": "ne",//过滤方式为 ne
"value":[1]
},
{
"field": "_widget_1732071387200",
"type": "number",//字段类型为 number
"method": "range",//过滤方式为 range
"value":[100,200]
},
{
"field": "_widget_1732071387200",
"type": "number",//字段类型为 number
"method": "empty",//过滤方式为 empty
},
{
"field": "_widget_1732071387200",
"type": "number",//字段类型为 number
"method": "not_empty",//过滤方式为 not_empty
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "eq",//过滤方式为 eq
"value":["111"]
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "ne",//过滤方式为 ne
"value":["111"]
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "in",//过滤方式为 in
"value":["111","2222"]
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "nin",//过滤方式为 nin
"value":["111","2222"]
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "empty",//过滤方式为 empty
},
{
"field": "_widget_1732071387199",
"type": "text",//字段类型为 text
"method": "not_empty",//过滤方式为 not_empty
},
{
"field": "_widget_1732071387202",
"type": "phone",//字段类型为 phone
"method": "like",//过滤方式为 like
"value":["188"]
},
{
"field": "_widget_1732071387202",
"type": "phone",//字段类型为 phone
"method": "verified",//过滤方式为 verified
},
{
"field": "_widget_1732071387202",
"type": "phone",//字段类型为 phone
"method": "unverified",//过滤方式为 unverified
},
{
"field": "_widget_1732071387202",
"type": "phone",//字段类型为 phone
"method": "empty",//过滤方式为 empty
},
{
"field": "_widget_1732071387202",
"type": "phone",//字段类型为 phone
"method": "not_empty",//过滤方式为 not_empty
},
{
"field": "_widget_1732071387206",
"type": "user",//字段类型为 user
"method": "empty"//过滤方式为 empty
},
{
"field": "_widget_1732071387206",
"type": "user",//字段类型为 user
"method": "not_empty"//过滤方式为 not_empty
},
]
}
}
响应参数:
参数 | 类型 | 说明 |
data | Array | 多条数据的集合 |
响应数据样例:
{
"data": [{
"_id": "59e9a2fe283ffa7c11b1ddbe",
"appId": "59264073a2a60c0c08e20bfb",
"entryId": "59264073a2a60c0c08e20bfd",
"creator": {
"name": "小简",
"username": "xiaojian",
"status": 1,
"type": 0,
"departments": [1, 3],
"integrate_id": "xiaojian"
},
"createTime": "2017-10-20T22:41:51.430Z",
"updateTime": "2017-10-20T11:12:15.293Z",
"_widget_1432728651402": "A班",
"_widget_1615777739673": [{
"_id": "604ed0298e2ade077c7245f1",
"_widget_1615777739744": "子表单数据1"
},
{
"_id": "604ed0298e2ade077c7245f2",
"_widget_1615777739744": "子表单数据2"
}
]
},
{
"_id": "59e9a2fe283ffa7c11b1ddbf",
"appId": "59264073a2a60c0c08e20bfb",
"entryId": "59264073a2a60c0c08e20bfd",
"creator": {
"name": "小简",
"username": "xiaojian",
"status": 1,
"type": 0,
"departments": [1, 3],
"integrate_id": "xiaojian"
},
"createTime": "2017-10-20T22:41:51.430Z",
"updateTime": "2017-10-20T11:12:15.293Z",
"_widget_1432728651402": "B班",
"_widget_1615777739673": [{
"_id": "604ed0298e2ade077c7245f3",
"_widget_1615777739744": "子表单数据1"
},
{
"_id": "604ed0298e2ade077c7245f4",
"_widget_1615777739744": "子表单数据2"
}
]
}
]
}
3. 注意事项
若要设置循环调取数据,可以利用 data_id 字段来设置参数避免调取重复数据。
如需要查询 230 条数据:
- 第一次查询时可以不传 data_id 字段,若设置 limit 为 100 ,则第一次返回了前 100 条数据;
- 第二次,用第 100 条数据的 data_id 进行查询,若设置 limit 为100,则第二次返回 101~200 这 100 条数据;
- 第三次,用第 200 条数据的 data_id 进行查询,若设置 limit 为100,则第三次返回 201~230 这 30 条数据。
由于第三次返回结果只有 30 条,未达到设置的 limit 上限100,则说明查询结束。