修改单条数据接口调试
1. 简介
1.1 接口简介
通过修改单条数据接口,可以对指定的单条数据进行修改。
注:使用 API 添加数据时,会触发的事件有新数据提交提醒、聚合表计算&校验、数据操作日志、数据量统计。也可以通过请求参数来控制是否发起流程。但是不会触发重复值校验、必填校验。
另外,系统字段 和以下所列举的字段不支持添加和修改数据:
- 分割线
- 手写签名
- 选择数据、查询
- 流水号(提交后系统生成)
1.2 接口版本说明
接口版本 | 更新时间 | 版本说明 |
v1 | 2018.6.21 | 部门和成员均使用_id为主键 |
v2 | 2019.6.21 | 在 v1 的基础上,成员字段使用 username 为主键,部门字段使用 dept_no 为主键 |
v3 | 2021.3.31 | 在 v2 的基础上,子表单新增数据 ID 参数,即为子表单中每条子数据新增一个数据 ID |
v4 | 2022.4.21 | 在 v3 的基础上,新增互联组织部门/成员获取,新增 type 参数类型:
|
v5 | 2022.10.28 | 在 v4 的基础上,接口请求频率由 5 次/秒提升至 20 次/秒; 参数 app_id 和 entry_id 放入 body,接口路由修改为 POST app/entry/data/update。 |
2. 接口调用
按照指定数据 ID 修改表单中的数据。
请求地址:https://api.jiandaoyun.com/api/v5/app/entry/data/update
请求频率:20 次/秒
请求方式:POST
请求参数:
参数 | 类型 | 必需 | 说明 | 默认 |
app_id | String | 是 | 应用ID | |
entry_id | String | 是 | 表单ID | |
data_id | String | 是 | 数据 ID | |
data | JSON | 是 | 数据内容,其他同新建单条数据接口,子表单需要注明子表单数据 ID | |
is_start_trigger | Bool | 否 | 是否触发智能助手 | false |
transaction_id | String | 否 | 事务 ID;transaction_id 用于绑定一批上传的文件,若数据中包含附件或图片控件,则 transaction_id 必须与“获取文件上传凭证和上传地址接口”中的 transaction_id 参数相同。 |
请求示例:
{
"app_id": "604eb6eea71d720006e1336e",
"entry_id": "604ecfca8e2ade077c72453a",
"transaction_id": "87cd7d71-c6df-4281-9927-469094395677", //事务ID
"data_id": "6052e8072315c0075001d65e",
"data": {
"_widget_1615777739654": {
"value": "张三"
},
"_widget_1615777739673": {
"value": [
{
"_widget_1615777739744": { // 未传子表单数据ID
"value": "张三"
}
},
{
"_id": {
"value": "606290aba392ca00076da000" // 错误的子表单数据ID
},
"_widget_1615777739744": {
"value": "李四"
}
},
{
"_id": {
"value": "606290aba392ca00076da0a9" // 正确的子表单数据ID
},
"_widget_1615777739744": {
"value": "王五"
}
}
]
}
},
"is_start_trigger": true
}
响应内容:
参数 | 类型 | 说明 |
data | JSON | 返回修改后的新数据,内容同查询单条数据接口 |
响应示例:
{
"data": {
"creator": {
"name": "小简",
"username": "xiaojian",
"status": 1,
"type": 0,
"departments": [1, 3],
"integrate_id": "xiaojian"
},
"updater": {
"name": "小简",
"username": "xiaojian",
"status": 1,
"type": 0,
"departments": [1, 3],
"integrate_id": "xiaojian"
},
"deleter": null,
"createTime": "2021-03-18T05:41:27.760Z",
"updateTime": "2021-03-30T02:46:21.563Z",
"deleteTime": null,
"_widget_1615777739654": "张三",
"_widget_1616052516346": "",
"_widget_1615777739673": [
{
"_id": "606290fd0094210006e97551", // 未传子表单数据ID则新建
"_widget_1615777739744": "张三"
},
{
"_id": "606290fd0094210006e97552", // 传入错误的子表单数据ID则新建
"_widget_1615777739744": "李四"
},
{
"_id": "606290aba392ca00076da0a9", // 传入正确的子表单数据ID则保持
"_widget_1615777739744": "王五"
}
],
"_id": "6052e8072315c0075001d65e",
"appId": "604eb6eea71d720006e1336e",
"entryId": "604ecfca8e2ade077c72453a",
"wx_open_id": "wx98fb14481b3ab5a3",
"wx_nickname": "jiandaoyun",
"wx_gender": "男"
}
}
3. 注意事项
1)如果调用修改单条数据 v3/v4/v5 接口时,未传递子表单数据 ID 或者 传递了错误的子表单数据 ID:
- 每次调用会清空请求的那条数据中原本的子表单数据,填入新请求的子表单数据;
- 给未传递子表单数据 ID 或传递了错误的子表单数据 ID 的子表单数据生成新的子表单数据 ID;
- 数据管理的数据日志中将会记录「子表单变更」,即使子表单内容没有发生任何变化。
注:
1)仅重置未传递或者传递错误的子表单数据 ID,调用一次重置一次。
2)若传递了正确的子表单数据 ID,则维持原本的子表单数据 ID 不变。
3)v1、v2 接口不发生变化。
示例如下:
原本的子表单中有 3 行数据,结构如下:
{
"_id": "605b5f68255d4845a73d3c0a", // <= 数据 ID
"_widget_1616600963783": "单行文本",
"_widget_1616600980550": [{
"_id": "605b5fa6255d4845a73d3c0b", // <= 子表单数据ID
"_widget_1616601008197": "子表单内的单行文本字段值1"
}, {
"_id": "605b5fdc255d4845a73d3c0c", // <= 子表单数据ID
"_widget_1616601008197": "子表单内的单行文本字段值2"
}, {
"_id": "605b5fdc255d4845a73d3c0d", // <= 子表单数据ID
"_widget_1616601008197": "子表单内的单行文本字段值3"
}]
}
假设在调用修改单条数据 v3/v4/v5 接口的过程中有一个子表单数据 ID 传递错误,有一个未传递,有一个传递正确,请求参数如下:
{
"data_id": "605b5f68255d4845a73d3c0a", // <= 数据 ID
"data": {
"_widget_1616600963783": {
"value": "单行文本修改"
},
"_widget_1616600980550": {
"value": [{
// <= 未传递子表单数据ID
"_widget_1616601008197": {
"value": "子表单内的单行文本字段值1修改"
}
}, {
"_id": {
"value": "jiandaoyun" // <= 传递了错误的子表单数据ID
},
"_widget_1616601008197": {
"value": "子表单内的单行文本字段值2修改"
}
}, {
"_id": {
"value": "605b5fdc255d4845a73d3c0d" // <= 传递了正确的子表单数据ID
},
"_widget_1616601008197": {
"value": "子表单内的单行文本字段值3修改"
}
}]
},
//... 其余参数
}
}
那么修改之后的数据结构如下,子表单中原本的第 1、2 行的数据 ID 发生变化:
{
"_id": "605b5f68255d4845a73d3c0a", // <= 数据 ID
"_widget_1616600963783": "单行文本",
"_widget_1616600980550": [{
"_id": "605b5fa6255d4845a73d3c0e", // <= 新的子表单数据ID
"_widget_1616601008197": "子表单内的单行文本字段值1修改"
}, {
"_id": "605b5fdc255d4845a73d3c0f", // <= 新的子表单数据ID
"_widget_1616601008197": "子表单内的单行文本字段值2修改"
}, {
"_id": "605b5fdc255d4845a73d3c0d", // <= 子表单数据ID不变
"_widget_1616601008197": "子表单内的单行文本字段值3修改"
}]
}
2)调用修改单条数据 v3/v4/v5 接口时,子表单及子字段必须整体请求和修改,不支持按照子表单数据 ID 只修改子表单对应行的数据,也不支持按照子字段的字段 ID 只修改对应子字段的数据。
- 如原子表单中原本有 3 条数据,请求参数中只写了 2 条数据,即使这 2 条数据的子表单行 ID 传递正确,修改后的子表单数据也只有 2 条。
- 原子表单中原本有 1 条数据,该条数据包含了 3 个子字段,若请求参数中只写了 2 个子字段,即使这 2 个子字段的字段 ID 传递正确,修改后的子表单数据也只有 2 个子字段。