表单&数据API
阅读人数：
978
- 开发准备
- 应用举例
- 字段别名
- 表单API
- 数据API
- POST - /api/v1/app/{app_id}/entry/{entry_id}/data 查询多条数据接口
- POST-/api/v1/app/{app_id}/entry/{entry_id}/data_by_sort 根据排序查询多条数据接口
- 数据筛选器
- POST - /api/v1/app/{app_id}/entry/{entry_id}/data_retrieve 查询单条数据接口
- POST - /api/v1/app/{app_id}/entry/{entry_id}/data_create 新建单条数据接口
- POST - /api/v1/app/{app_id}/entry/{entry_id}/data_update 修改单条数据接口
- POST - /api/v1/app/{app_id}/entry/{entry_id}/data_delete 删除单条数据接口
- 控件与数据类型对照表
- API操作关联关系
开发准备
开发前，请仔细阅读开发指南
注：以下所有接口路径中的app_id和entry_id分别表示应用ID和该应用内的表单ID，因此app_id+entry_id表示全局唯一的表单ID，前往系统管理中的API文档进行查看。
应用举例
API & 订单管理
在百宝云中建立了一个订单表单，用于统计订单信息。销售渠道一般分为线上商城销售和线下销售，线下销售通常需要销售手动在百宝云中录入订单。但是线上渠道用户自主下单后会生成一个订单，此时这个订单可以通过新增单条数据API接口直接在百宝云中生成一条订单记录，这样我们就不需要一个人专门把网上的订单一条条手动录入百宝云。手动录入不仅工作量很大，而且容易出错。
API & 项目管理
当使用百宝云做项目管理流程控制时，一般财务收款都是有单独的一套系统，此时可以通过修改单条数据API接口将财务软件中的收款信息推送到百宝云来，从而修改对应的项目信息。
字段别名
字段别名（控件别名）默认为系统自动生成的数值字符串，可以修改。
表单API
POST - /api/v1/app/{app_id}/entry/{entry_id}/widgets 表单字段查询接口
获取指定表单的控件/字段信息，除分割线控件和关联查询控件以外。具体可以查阅文档最后的 控件与数据类型对照表。
请求参数： 无
响应内容：
| 参数 | 含义 |
| widgets | 控件信息 |
| widgets[].name | 控件别名 |
| widgets[].title | 控件标题 |
| widgets[].type | 控件类型；每种控件类型都有对应的数据类型 |
| widgets[].data | 仅子表单控件有；数组里包含了每个子控件的信息 |
响应数据样例：
{
"widgets": [
{
"name": "_widget_1558765248187",
"title": "单行文本",
"type": "text"
},
{
"name": "多行文本",
"title": "多行文本",
"type": "textarea"
},
{
"name": "数字",
"title": "数字",
"type": "number"
},
{
"name": "日期时间",
"title": "日期时间",
"type": "datetime"
},
{
"name": "单选按钮组",
"title": "单选按钮组",
"type": "radiogroup"
},
{
"name": "复选框组",
"title": "复选框组",
"type": "checkboxgroup"
},
{
"name": "下拉复选框",
"title": "下拉复选框",
"type": "combocheck"
},
{
"name": "下拉框",
"title": "下拉框",
"type": "combo"
},
{
"name": "定位",
"title": "定位",
"type": "location"
},
{
"name": "地址",
"title": "地址",
"type": "address"
},
{
"name": "_widget_1558929030197",
"title": "附件",
"type": "upload"
},
{
"name": "图片",
"title": "图片",
"type": "image"
},
{
"name": "子表单",
"title": "子表单",
"type": "subform",
"data": [
{
"name": "子表单单行文本",
"title": "单行文本",
"type": "text"
},
{
"name": "子表单多行文本",
"title": "多行文本",
"type": "textarea"
}
]
},
{
"name": "_widget_1558929030271",
"title": "关联数据",
"type": "linkdata"
},
{
"name": "_widget_1558929030284",
"title": "手写签名",
"type": "signature"
},
{
"name": "成员单选",
"title": "成员单选",
"type": "user"
},
{
"name": "成员多选",
"title": "成员多选",
"type": "usergroup"
},
{
"name": "部门单选",
"title": "部门单选",
"type": "dept"
},
{
"name": "部门多选",
"title": "部门多选",
"type": "deptgroup"
}
]
}
数据API
POST - /api/v1/app/{app_id}/entry/{entry_id}/data 查询多条数据接口
该接口的返回数据，始终按照提交时间正序排列。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| data_id | String | 上一次查询数据结果的最后一条数据的ID，没有则留空 | |
| fields | Array | 需要查询的数据字段 | |
| filter | JSON | 数据筛选器 | |
| limit | Number | 查询的数据条数，1~100，默认100 |
请求示例：
{
"data_id":"53b6b1251b4eab93d38cb33b",
"fields":["_widget_1558765248187","多行文本","数字","子表单"],
"limit":10,
"filter":{
"rel": "and",
"cond": [
{
"field":"creator",
"method":"in",
"value":["575ffc5e885898ce0d2afe41", "56979d1d1eea475f2848249b"]
},
{
"field": "_widget_1558765248187",
"method": "eq",
"value":[454],
"hasEmpty":true
},
{
"field":"数字",
"method":"ne",
"value":[666]
}
]
}
}
响应参数：
| 参数 | 类型 | 说明 |
| data | Array | 多条数据的集合 |
响应数据样例：
{
"data": [
{
"appId": "539543cee19942ea8bb5e744",
"entryId": "56af3c8b7f7f039c93108be8",
"_id": "5bb6e4e013d46e148a9da655",
"_widget_1558765248187": "454",
"多行文本": "sdfsdf",
"数字": "-666.55"
},
{
"appId": "539543cee19942ea8bb5e744",
"entryId": "56af3c8b7f7f039c93108be8",
"_id": "5bbfe3ab42ba31e44c5be199",
"_widget_1558765248187": "454",
"多行文本": "sdfsdf",
"数字": "-666.55"
}
]
}
请注意： 查询到的数据内容中，除了控件字段以外，还有一些系统字段
如下表：
| 系统字段 | 字段别名 | 数据类型 | 数据样例 | 备注 |
| appId | appId | String | “539543cee19942ea8bb5e744” | appId+entryId保证表单ID的唯一性 |
| entryId | entryId | String | “50dafd850f3fc191513f2f21” | appId+entryId保证表单ID的唯一性 |
| 数据ID | _id | String | “5bb6e4e013d46e148a9da655” | 全局唯一 |
| 提交时间 | String | “2019-01-01 10:10:10” | ||
| 提交人 | JSON | {"_id": “575ffc5e885898ce0d2afe41”, “name”: “小云”} | ||
| 修改时间 | String | “2019-01-01 10:10:10” | ||
| 修改人 | JSON | {"_id": “575ffc5e885898ce0d2afe41”, “name”: “小云”} | ||
| 删除人 | JSON | {"_id": “575ffc5e885898ce0d2afe41”, “name”: “小云”} | ||
| 删除时间 | String | “2019-01-01 10:10:10” | ||
| 流程状态（仅流程表单） | flowState | 0 | 该字段仅流程表单支持。2表示流程手动结束；1表示流程已结束；0表示流程进行中 |
POST-/api/v1/app/{app_id}/entry/{entry_id}/data_by_sort 根据排序查询多条数据接口
请求参数：
| 参数 | 必须 | 类型 | 说明 |
| limit | Number | 查询的数据条数，1~100，默认100 | |
| skip | Number | 翻页起始值索引 | |
| fields | Array | 需要查询的数据字段 | |
| filter | JSON | 数据筛选器 | |
| sort | JSON | 排序（asc：正序；desc：倒序），不限制排序字段的数量，复选框组、下拉复选框、地址、定位、图片、附件、手写签名、成员单选、成员多选、部门单选、部门多选不可作为排序字段 |
请求示例：
{
"limit": 100,
"skip": 0,
"fields": [
"_widget_1499052693182",
"_widget_1499052693195",
"_widget_1499052693206"
],
"filter": {
"rel": "and",
"cond": [
{
"field": "_widget_1499052693182",
"method": "empty"
},
{
"field": "_widget_1499052693195",
"method": "not_empty"
},
{
"field": "_widget_1499052693206",
"method": "empty"
}
]
},
"sort": {
"_widget_1499052693182": "desc",
"_widget_1499052693195": "asc"
}
}
响应数据样例：
{
"data": {
"appId": "5b88531dc22c4e4c7755116f",
"entryId": "56e26c5747ae8869481b417f",
"_id": "5bb6e4e013d46e148a9da655",
"_widget_1555926403587": "张三",
"_widget_1555926403600": "张三",
"_widget_1555926403640": 7,
"_widget_1555926403652": "2019-01-01 10:10:10",
"creator": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
"createTime": "2019-01-01 10:10:10",
"updateTime": "2019-01-01 10:10:10",
"updater": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
"deleter": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
}
}
}
数据筛选器
查询多条数据接口同时也支持过滤。可通过filter参数进行数据过滤。
筛选参数结构如下：
| 参数 | 必需 | 类型 | 说明 |
| rel | 是 | String | 筛选组合关系；“and”(满足所有过滤条件), “or”(满足任一过滤条件) |
| cond | 是 | [JSON] | 过滤条件列表 |
过滤条件参数如下：
| 参数 | 必需 | 类型 | 说明 |
| field | 是 | String | 字段名 |
| method | 是 | String | 过滤方法； eq （等于）， ne（不等于）， all（同时包含） ，in（等于任意一个） ，nin（不等于任意一个），like（包含） ，unlike（不包含），empty（为空）， not_empty（不为空）， gt（大于），gte（大于等于），lt（小于）， lte（小于等于），range（选择范围，在x与y之间，并且包含x和y本身） |
| value | Array | 过滤值 | |
| hasEmpty | Bool | 是否未填写 |
目前支持如下字段：
| 字段类型 | 支持的过滤方式 | 说明 |
| flowState | eq，ne | 流程状态，仅对流程表单有效 |
| 日期时间/数字/提交时间/更新时间 | eq，ne，gt，gte，lt，lte，range，empty，not_empty | |
| 单行文本/下拉框/单选按钮组 | eq，ne，in，nin，like，unlike，empty，not_empty | |
| 多行文本 | like，unlike，empty，not_empty | |
| 附件/图片/手写签名 | empty，not_empty | |
| 定位/地址 | empty，not_empty，all，nin | |
| 复选框组/下拉复选框 | eq，empty，not_empty，all，in | |
| 成员单选/部门单选/提交人 | eq，ne，in，nin，empty，not_empty | |
| 成员多选/部门多选 | in，all，eq，empty，not_empty |
筛选示例：
{
"filter": {
"rel": "and", // 或者 "or"
"cond": [
// 过滤条件
{
"field": "flowState",
"method": "eq",
"value": [1]
}, {
"field": "图片",
"method": "empty"
}, {
"field": "单行文本",
"method": "in",
"value": ["apple", "pen"]
}, {
"field": "时间",
"method": "range",
"value": ["2019-06-11 00:00:00", "2019-06-28 23:59:59"]
}, {
"field": "多行文本",
"method": "like",
"value": ["ddd"] //包含“ddd”的数据
}
]
}
}
POST - /api/v1/app/{app_id}/entry/{entry_id}/data_retrieve 查询单条数据接口
按照指定数据ID获取表单中的数据。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| data_id | 是 | String | 数据ID |
请求示例：
POST /api/v1/app/59264073a2a60c0c08e20bfb/entry/59264073a2a60c0c08e20bfd/data_retrieve
{
"data_id": "59e9a2fe283ffa7c11b1ddbf"
}
响应参数：
| 参数 | 类型 | 说明 |
| data | JSON | 单条数据 |
响应数据样例：
{
"data": {
"appId": "539543cee19942ea8bb5e744",
"entryId": "50dafd850f3fc191513f2f21",
"_id": "5bb6e4e013d46e148a9da655",
"_widget_1558765248187": "张三",
"聚合表验证数字": 7,
"多行文本": "百宝云webapi",
"数字": 7,
"日期时间": "2019-01-01 10:10:10",
"单选按钮组": "一年级",
"复选框组": [
"选项1",
"选项2"
],
"下拉复选框": [
"选项1",
"选项2"
],
"下拉框": "女",
"定位": {
"province": "湖南省",
"city": "长沙市",
"district": "芙蓉区",
"detail": "韶山北路86号鑫天大厦",
"lnglatXY": [
113.002864,
28.199614
]
},
"地址": {
"province": "湖南省",
"city": "长沙市",
"district": "芙蓉区",
"detail": "韶山北路86号鑫天大厦"
},
"_widget_1558929030197": [
{
"name": "私有云介绍.pdf",
"size": 524288,
"mime": "application/pdf",
"url": "http://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2"
},
{
"name": "定制介绍.pdf",
"size": 524288,
"mime": "application/pdf",
"url": "http://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2"
}
],
"图片": [
{
"name": "bby.png",
"size": 3762,
"mime": "image/png",
"url": "http://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2"
},
{
"name": "image2.png",
"size": 3762,
"mime": "image/png",
"url": "http://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2"
}
],
"子表单": [
{
"子表单单行文本": "张三",
"子表单多行文本": "百宝云webapi"
}
],
"_widget_1558929030271": {
"id": "5b237548b22ab14884086cc0",
"key": "百宝云"
},
"_widget_1558929030284": {
"name": "signature_1238921858.png",
"size": 1024,
"mime": "image/png",
"url": "http://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2"
},
"成员单选": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
"成员多选": [
{
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
{
"_id": "575ffc5e885898ce0d2afe41",
"name": "小宝"
}
],
"部门单选": {
"_id": "59daab24c91306a9239b7ca0",
"name": "经理部"
},
"部门多选": [
{
"_id": "59daab24c91306a9239b7ca0",
"name": "经理部"
},
{
"_id": "59daab24c91306a9239b7ca1",
"name": "市场部"
}
],
"creator": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
"createTime": "2019-01-01 10:10:10",
"updateTime": "2019-01-01 10:10:10",
"updater": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
},
"deleter": {
"_id": "575ffc5e885898ce0d2afe41",
"name": "小云"
}
}
}
POST - /api/v1/app/{app_id}/entry/{entry_id}/data_create 新建单条数据接口
在指定表单中添加一条数据。
请注意： 使用API添加数据时，会触发的事件有新数据提交提醒、聚合表计算&校验、数据量统计。也可以通过请求参数来控制是否发起流程。但是不会触发重复值校验和必填校验。
另外，系统字段 和 以下所列举的控件 不支持添加和修改数据：
- 分割线
- 手写签名
- 关联数据、关联查询
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| data | 是 | JSON | 数据内容 |
| is_start_workflow | 否 | Boolean | 用来控制是否触发流程，默认不触发流程 |
| is_start_event | 否 | Boolean | 是否触发事件（模块事件/_form事件） |
| operator | 否 | String | 操作人_id，默认使用应用所有者的_id |
请求示例：
{
"data": {
"_widget_1558765248187": "张三",
"聚合表验证数字": 8,
"多行文本": "百宝云webapi",
"数字": 8,
"日期时间": "2019-01-01 11:11:11",
"单选按钮组": "一年级",
"复选框组": [
"选项1",
"选项2"
],
"下拉复选框": [
"选项1",
"选项2"
],
"下拉框": "女",
"定位": {
"province": "湖南省",
"city": "长沙市",
"district": "芙蓉区",
"detail": "韶山北路",
"lnglatXY": [
112.99627,
28.19393
]
},
"地址": {
"province": "湖南省",
"city": "长沙市",
"district": "芙蓉区",
"detail": "韶山北路"
},
"图片": [
"https://doc.baibaoyun.com/static/index/images/tu_1_03.png",
"https://www.baibaoyun.com/static/index/images/tu_1_03.png"
],
"子表单": [
{
"子表单单行文本": "张三",
"子表单多行文本": "百宝云webapi"
},
{
"子表单单行文本": "李四",
"子表单多行文本": "百宝云"
}
],
"成员单选": "5af263d45e67aaf5b09033c7",
"成员多选": [
"5af263d45e67aaf5b09033c7",
"5af263d45e67aaf5b09033c9"
],
"部门单选": "5af263d45e67aaf5b09033c7",
"部门多选": [
"5af263d45e67aaf5b09033c7",
"5af263d45e67aaf5b09033c9"
]
},
"is_start_workflow": true,
"is_start_event": true,
"operator": ""
}
响应参数
| 参数 | 类型 | 说明 |
| data | JSON | 返回提交后的完整数据，内容同查询单条数据接口 |
响应数据样例
{
"data": {}
}
POST - /api/v1/app/{app_id}/entry/{entry_id}/data_update 修改单条数据接口
按照指定数据ID修改表单中的数据。
请注意： 使用API修改数据时，会触发的事件有聚合表计算&校验、数据量统计。不进行重复值校验、必填校验等。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| data_id | 是 | String | 数据ID |
| data | 是 | JSON | 数据内容，同数据提交 |
| is_start_event | 否 | Boolean | 是否触发事件（模块事件/_form事件） |
| operator | 否 | String | 操作人_id，默认使用应用所有者的_id |
请求示例：
{
"data_id": "59264073a2a60c0c08e20bfb",
"data": {}
}
响应参数：
| 参数 | 类型 | 说明 |
| data | JSON | 返回修改后的新数据，内容同查询单条数据接口 |
响应数据样例：
{
"data": {}
}
POST - /api/v1/app/{app_id}/entry/{entry_id}/data_delete 删除单条数据接口
按照指定数据ID从表单中删除数据，删除的数据进入回收站。
请求参数：
| 参数 | 必需 | 类型 | 说明 |
| data_id | 是 | String | 数据ID |
| is_start_event | 否 | Boolean | 是否触发事件（模块事件/_form事件） |
| operator | 否 | String | 操作人_id，默认使用应用所有者的_id |
响应数据样例：
{
"status": "success"
}
控件与数据类型对照表
| 控件名称 | 控件类型 | 数据类型 | 数据样例 | 备注 |
| 单行文本 | text | String | “张三” | |
| 多行文本 | textarea | String | “百宝云webapi” | |
| 数字 | number | Number | 7 | |
| 日期时间 | datetime | String | “2019-01-01 11:10:11” | |
| 单选按钮组 | radiogroup | String | “一年级” | |
| 复选框组 | checkboxgroup | Array | [“选项1”,“选项2”] | |
| 下拉框 | combo | String | “女” | |
| 下拉复选框 | combocheck | Array | [“选项1”,“选项2”] | |
| 地址 | address | JSON | {province: "湖南省", city: "长沙市", district: "芙蓉区", detail: "袁家岭"} | |
| 定位 | location | JSON | {province: "湖南省", city: "长沙市", district: "芙蓉区", detail: "袁家岭", lnglatXY: [113.002864, 28.199614]} | lnglatXY表示[经度, 纬度] |
| 图片 | image | Array | [ { "name": "img.png", "size": 3762, "mime": "image/png", "url": "https://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2" }, { "name": "img1.png", "size": 3762, "mime": "image/png", "url": "https://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUX4Vp2" } ] | 数据中包含的url为图片链接 |
| 附件 | upload | Array | [ { "name": "接口.pdf", "size": 37602, "mime": "application/pdf", "url": "https://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6bUVp2" }, { "name": "百宝云.pdf", "size": 37602, "mime": "application/pdf", "url": "https://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6X4Vp2" } ] | 数据中包含的url为附件链接 |
| 子表单 | subform | Array | ||
| 关联数据 | linkdata | JSON | {“id”:“5b237548b22ab14884086cc0”,“key”:“接口”} | id表示所关联数据的ID；key表示主键字段的值 |
| 手写签名 | signature | JSON | {“name”:“signature_1238921857.png”,“size”:1024,“mime”:“image/png”,“url”:“https://qiniu.baibaoyun.com/FvXfzy2nqPP12YP5cTeH6X4p2”} | 数据中包含的url为手写签名的图片链接 |
| 成员单选 | user | JSON | { "name": "小云", "_id": "55cb7d57f7a190e382857189" } | 成员信息中_id表示百宝云中的用户id；name表示用户昵称 |
| 成员多选 | usergroup | Array | [ { "name": "小云", "_id": "55cb7d57f7a190e382857189" }, { "name": "小宝", "_id": "575ffc5e885898ce0d2af791" } ] | |
| 部门单选 | dept | JSON | { "name": "销售部", "_id": "59daab24c91306a9239b7ca0" } | |
| 部门多选 | deptgroup | Array | [ { "name": "销售部", "_id": "59daab24c91306a9239b7ca0" }, { "name": "人事部", "_id": "5014a86b688ff0ec55a946d9" } ] |
API操作关联关系
| - | create | update | delete |
| 数据消息推送 | 记录 | 记录 | 不记录 |
| 触发聚合表 | 记录 | 记录 | 记录 |
| 数据动态 | 记录 | 记录 | 记录 |
| 事件/模块 | 可记录 | 可记录 | 可记录 |
| 重复值校验 | 不校验 | 不校验 | - |
| 表单校验 | 不校验 | 不校验 | - |
| 必填校验 | 不校验 | 不校验 | - |
| 流程节点校验 | 不校验 | 不校验 | - |
| 触发流程 | 可记录 | 不记录 | - |
| 聚合表校验 | 校验 | 校验 | 校验 |
| 字段联动、公式 | 不记录 | 不记录 | - |