表单和数据接口 - 简道云

表单和数据接口

1. 简介

表单和数据接口包括表单接口和数据接口：

接口类型	接口文档	接口说明
表单接口	表单接口	可以获取指定表单的字段/字段信息。
数据接口	查询单条数据接口	按照指定数据 ID 获取表单中的数据。
	查询多条数据接口	该接口的返回数据，始终按照数据 ID 正序排列。
	新建单条数据接口	按照指定数据 ID 获取表单中的数据。
	新建多条数据接口	创建多条数据接口最多支持 100 条数据。
	修改单条数据接口	按照指定数据 ID 修改表单中的数据。
	修改多条数据接口	批量更新多条数据，最多支持修改 100 条数据。
	删除单条数据接口	按照指定数据 ID 从表单中删除数据。

开发前，请仔细阅读开发指南。

2. 字段名

表单字段一旦添加，会以 _widget_ 为前缀的固定字段 ID 来表示字段，无论修改字段的任何信息都不会变更字段ID。

每个字段都对应着一个字段别名。用户可以自己设置字段别名。如果设置了别名，则在之后所有的 API 中，字段所对应的字段名都将以字段别名作为实际字段名；如果没有设置别名，则字段将采用字段 ID 作为实际字段名。

字段别名在「扩展功能>>数据推送>>设置字段别名」处进行设置。如下图所示：

3. 字段与数据类型对照表

3.1 表单字段

字段名称	字段类型	数据类型	数据样例	备注
单行文本	text	String	“张三”	——
多行文本	textarea	String	“我爱简道云”
流水号	sn	String	“00001”
数字	number	Number	10
日期时间	datetime	String	“2018-01-01T10:10:10.000Z”	UTC 统一时间格式的字符串
日期时间	datetime	String	{ “field”:“createTime”, "method":"range", "value":["2022-01-01",null] }	大于某个时间点的写法
单选按钮组	radiogroup	String	“一年级”	——
复选框组	checkboxgroup	Array	[“选项1”,“选项2”]
下拉框	combo	String	“女”
下拉复选框	combocheck	Array	[“选项1”,“选项2”]
地址	address	JSON	{ "province": "江苏省", "city": "无锡市", "district": "梁溪区", "detail": "清扬路138号茂业天地" }
定位	location	JSON	{ "province": "江苏省", "city": "无锡市", "district": "梁溪区", "detail": "清扬路138号茂业天地", "lnglatXY": [ 120.31237, 31.49099 ] }	lnglatXY 表示[经度, 纬度]
图片	image	Array	[ { "name": "image1.png", "size": 262144, "mime": "image/png", "url": "https://files.jiandaoyun.com/cqbrmcwhxm" }, { "name": "image2.png", "size": 262100, "mime": "image/png", "url": "https://files.jiandaoyun.com/cqbrywmwh" } ]	数据中包含的url为图片链接，15天内有效
附件	upload	Array	[ { "name": "产品说明文档.pdf", "size": 524288, "mime": "application/pdf", "url": "https://files.jiandaoyun.com/ojiwvfeyt" }， [ { "name": "开发架构文档.pdf", "size": 524288, "mime": "application/pdf", "url": "https://files.jiandaoyun.com/mst" } ]	数据中包含的url为附件链接，15天内有效
子表单	subform	Array	[ { "_id":"5b237548b22ab14884086cc0", "_widget_1529400746031"：...... }, { "_id":"5b237548b22ab14884086cc1", "_widget_1529400746031"：...... } ]	_id 为子表单数据ID，由服务端生成
选择数据	linkdata	JSON	{ "id": "5b237548b22ab14884086cc0" }	id 表示所关联数据的ID
手写签名	signature	JSON	{ "name": "signature_1238921857.png", "size": 1024, "mime": "image/png", "url": "https://files.jiandaoyun.com/ojiwsdf" }	数据中包含的 url 为手写签名的图片链接，15 天内有效
成员单选	user	JSON	{ "name": "小简", "username": "xiaojian", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "xiaojian" }	成员信息中username表示通讯录的成员编号（企业内唯一），如果是企业集成模式下同步的用户，相当于是钉钉或者企业微信的 user_id；name 表示用户昵称 status 对应的逻辑: -1 离职 0 未加入 1 已加入
成员多选	usergroup	Array	[ { "name": "小简", "username": "xiaojian", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "xiaojian" } ]	status 对应的逻辑: -1 离职 0 未加入 1 已加入
部门单选	dept	JSON	{ "name": "经理部", "dept_no": 1, "type": 0, "parent_no": 2, "status": 1, "integrate_id": 1 }	部门信息中 dept_no 表示通讯录的部门编号（企业内唯一），如果是企业集成模式下同步的用户，相当于是钉钉或者企业微信的部门编号；name 表示部门名称
部门多选	deptgroup	Array	[ { "name": "经理部", "dept_no": 1, "type": 0, "parent_no": 2, "status": 1, "integrate_id": 1 } ]
手机	phone	JSON	{ "phone": "13566666666", "verified": true }	phone表示手机号，verified为布尔型，表示是否已验证。注：提交数据时verified不需要提交。

3.2 系统字段

查询到的数据内容中，除了表单字段以外，还有一些系统字段。如下表：

系统字段	字段名	数据类型	数据样例	备注
应用Id	appId	String	“5b237267b22ab14884086c49”	全局唯一性ID
表单Id	entryId	String	“5b237267b22ab14884086cc9”	appId+entryId保证表单ID的唯一性
数据ID	_id	String	“5b237267b22ab14884086c50”	数据全局唯一性ID
扩展字段	ext	String	“广州”	-
提交时间	createTime	String	“2018-01-01T10:10:10.000Z”	-
提交人	creator	JSON	{ "name": "小简", "username": "xiaojian", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "xiaojian" }	status 对应的逻辑: -1 离职 0 未加入 1 已加入
修改时间	updateTime	String	“2018-01-01T10:10:10.000Z”	-
修改人	updater	JSON	{ "name": "小简", "username": "xiaojian", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "xiaojian" }	status 对应的逻辑: -1 离职 0 未加入 1 已加入
删除人	deleter	JSON	{ "name": "小简", "username": "xiaojian", "status": 1, "type": 0, "departments": [1, 3], "integrate_id": "xiaojian" }	status 对应的逻辑: -1 离职 0 未加入 1 已加入
流程状态 ^{*仅流程表单}	flowState	0	该字段仅流程表单支持。2表示流程手动结束；1表示流程流转完成；0表示流程进行中。	-

3.3 时间格式限制

通过 API 写入数据时，支持的时间格式如下：

支持格式	示例	备注
ISO日期格式	'2018-11-09T10:00:00Z' '2018-11-09T10:00:00'	使用 ISO 日期格式查询时，最后的 Z 代表 UTC 的 0 时区，故查询结果会差 8个小时。
毫秒时间戳	1639106951523 异常输入: 1639106951 0	——
rfc 3339 yyyy-MM-dd HH:mm:ss yyyy-MM-dd	'2020-06-04 14:41:54.767135400+08:00' '2021-10-10 10:10:10' '2021-10-10'	——

注：不允许的输入会转为空值传入。

不支持的格式示例：

null,// 无输入, 也就是空日期
undefined,
'',
'Thu, 04 Jun 2020 13:54:52 +0800',// IETF日期格式: 不支持(原先支持)
'2021/10/10 10:10:10',// 不支持(原先支持)
["2021-03-19 23:10:00"],// 不支持(原先支持)
'Mar 31 10:10:43 UTC+0800 2012',// 不支持
'2020-06-04T14:41:54,767135400+08:00',//不支持
'~','     ',// 不支持

4. API操作关联关系

功能	create	update	delete	batch_create	batch_update
数据工厂延时计算	触发	触发	触发	触发	触发
数据消息推送	触发	触发	不触发	触发	触发
触发聚合表	触发	触发	触发	触发	触发
数据操作日志	记录	记录	记录	记录	记录
webhook数据推送	不触发	不触发	不触发	不触发	不触发
智能助手	可触发	可触发	可触发	不触发	不触发
重复值校验	不校验	不校验	-	不校验	不校验
表单校验	不校验	不校验	-	不校验	不校验
必填校验	不校验	不校验	-	不校验	不校验
流程节点校验	不校验	不校验	-	不校验	不校验
触发流程	可触发	不触发	-	可触发	不触发
聚合表校验	校验	校验	触发	不校验	不校验
字段联动、公式	不触发	不触发	-	不触发	不触发
表单推送提醒	触发	触发	-	不触发	不触发

5. 注意事项

所有接口路径中的 app_id 和 entry_id 分别表示应用 ID 和该应用内的表单 ID，因此 app_id+entry_id 表示全局唯一的表单ID，可以前往开放平台内的参数说明中进行查看，也可前往 API调试台进行接口调试。

示例：

接口：查询单条数据接口
请求地址：https://api.jiandaoyun.com/api/v2/app/{app_id}/entry/{entry_id}/data_retrieve

将上述请求地址中的 app_id 和 entry_id 替换为自己需要查询的表单数据的应用 ID 和表单 ID，即为真正的请求地址。如：

https://api.jiandaoyun.com/api/v2/app/61947e7cfcc66f0008341b8b/entry/5d5e535132b989071ad102a0/data_retrieve