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 |
数据消息推送 | 记录 | 记录 | 不记录 |
触发聚合表 | 记录 | 记录 | 记录 |
数据动态 | 记录 | 记录 | 记录 |
事件/模块 | 可记录 | 可记录 | 可记录 |
重复值校验 | 不校验 | 不校验 | - |
表单校验 | 不校验 | 不校验 | - |
必填校验 | 不校验 | 不校验 | - |
流程节点校验 | 不校验 | 不校验 | - |
触发流程 | 可记录 | 不记录 | - |
聚合表校验 | 校验 | 校验 | 校验 |
字段联动、公式 | 不记录 | 不记录 | - |