修改单条数据接口 - 简道云

修改单条数据接口调试

Yonne更新于2025-03-10阅读时长：22分钟

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 参数类型： 0：内部 2：外部
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 参数相同。

请求示例：

xxxxxxxxxx
 
{
   "app_id": "604eb6eea71d720006e1336e",
   "entry_id": "604ecfca8e2ade077c72453a",
  "transaction_id": "87cd7d71-c6df-4281-9927-469094395677",   //事务ID
    "data_id": "6052e8072315c0075001d65e",
    "data": {
        "_widget_1615777739654": {
            "value": "张三"
        },
        "_widget_1725969783950": {
            "value": "67221b4fac0a62ac8f43a1c3"//关联数据
        },
        "_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	返回修改后的新数据，内容同查询单条数据接口

响应示例：

xxxxxxxxxx
 
{
    "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_1725969783950": "67221b4fac0a62ac8f43a1c3",//关联数据
        "_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 行数据，结构如下：

​x
 
{
    "_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 传递错误，有一个未传递，有一个传递正确，请求参数如下：

xxxxxxxxxx
 
{
    "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 发生变化：

xxxxxxxxxx
 
{
    "_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 个子字段。