查询多条数据接口 - 简道云

查询多条数据接口调试

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 参数类型： 0：内部 2：外部
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	过滤方法： “not_empty”(不为空)， “empty”(为空)， “eq”(等于)， “in”(等于任意一个)，最多可传递 200 个 “range”(在x与y之间，并且包含x和y本身)， “nin”(不等于任意一个)，最多可传递 200 个 “ne”(不等于), “like”(包含) “verified“(表示填写了手机号且已验证的值) “unverified“(表示填写了手机号但未验证值)
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": "_widget_1508400000001",
                "type": "text",
                "method": "empty"
            },
            {
                "field": "_widget_1508400000002",
                "type": "number",
                "method": "not_empty"
            },
            {
                "field": "flowState",
                "type": "flowstate",
                "method": "eq",
                "value": [0]
            },
             {
                "field":"createTime",
                "method":"range",
                "value":["2022-01-01",null]
            }
        ]
    }
}

响应参数：

参数	类型	说明
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，则说明查询结束。