表单和数据接口

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 统一时间格式的字符串

{

“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

文档内容是否对您有帮助?
有帮助
没帮助没帮助
如需获取即时帮助,请联系技术支持
咨询
扫码领取100+零代码资料简道云官方微信号400-111-0890
图标在线咨询
立即体验