飞书开放平台 Server API 文档

主题

更新记录 ​

更新多维表格数据表中的一条记录。

前提条件 ​

调用此接口前，请确保当前调用身份（tenant_access_token 或 user_access_token）已有多维表格的编辑等文档权限，否则接口将返回 HTTP 403 或 400 状态码。了解更多，参考如何为应用或用户开通文档权限。

注意事项 ​

  • 从其它数据源同步的数据表，不支持对记录进行增加、删除、和修改操作。
  • 更新记录为增量更新，仅更新传入的字段。如果想对记录中的某个字段值置空，可将字段设为 null，例如：
json
{
  "fields": {
    "文本字段": null
  }
}

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/records/:record_id
HTTP MethodPUT
接口频率限制50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可base:record:update 更新记录 bitable:app 查看、评论、编辑和管理多维表格
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.base:readonly 获取用户基本信息 contact:user.employee_id:readonly 获取用户 user ID contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
app_tokenstring多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： app_token.png
- 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。
了解更多，参考多维表格 app_token 获取方式。
示例值："appbcbWCzen6D8dezhoCH2RpMAh"
table_idstring多维表格数据表的唯一标识。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id

示例值："tblsRc9GRRXKqhvW"
record_idstring数据表中一条记录的唯一标识。通过查询记录接口获取。
示例值："recqwIwhc6"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
ignore_consistency_checkboolean否是否忽略一致性读写检查，默认为 false，即在进行读写操作时，系统将确保读取到的数据和写入的数据是一致的。可选值： - true：忽略读写一致性检查，提高性能，但可能会导致某些节点的数据不同步，出现暂时不一致 - false：开启读写一致性检查，确保数据在读写过程中一致
示例值：true

请求体 ​

名称类型必填描述
fieldsmap<string, union>是要更新的记录的数据。你需先指定数据表中的字段（即指定列），再传入正确格式的数据作为一条记录。
注意：
该接口支持的字段类型及其描述如下所示： - 文本：原值展示，不支持 markdown 语法 - 数字：填写数字格式的值 - 单选：填写选项值，对于新的选项值，将会创建一个新的选项 - 多选：填写多个选项值，对于新的选项值，将会创建一个新的选项。如果填写多个相同的新选项值，将会创建多个相同的选项 - 日期：填写毫秒级时间戳 - 复选框：填写 true 或 false - 条码 - 人员：填写用户的 open_id、union_id 或 user_id，类型需要与 user_id_type 指定的类型一致 - 电话号码：填写文本内容 - 超链接：参考以下示例，text 为文本值，link 为 URL 链接 - 附件：填写附件 token，需要先调用上传素材或分片上传素材接口将附件上传至该多维表格中 - 单向关联：填写被关联表的记录 ID - 双向关联：填写被关联表的记录 ID - 地理位置：填写经纬度坐标
不同类型字段的数据结构请参考数据结构概述。
示例值：{"文本":"HelloWorld"}

请求体示例 ​

json
{
    "fields": {
        "索引": "索引列文本类型",
        "文本": "文本内容",
        "条码":"qawqe",
        "数字": 100,
        "单选": "选项3",
        "多选": [
            "选项1",
            "选项2"
        ],
        "货币":3,
        "评分":3,
        "进度":0.25,
        "日期": 1674206443000,
        "复选框": true,
        "人员": [
            {
                "id": "ou_2910013f1e6456f16a0ce75ede950a0a"
            },
            {
                "id": "ou_e04138c9633dd0d2ea166d79f548ab5d"
            }
        ],
        "群组":[
            {
                "id": "oc_cd07f55f14d6f4a4f1b51504e7e97f48"
            }
        ],
        "电话号码": "13026162666",
        "超链接": {
            "text": "飞书多维表格官网",
            "link": "https://www.feishu.cn/product/base"
        },
        "附件": [
            {
                "file_token": "Vl3FbVkvnowlgpxpqsAbBrtFcrd"
            }
        ],
        "单向关联": [
            "recHTLvO7x",
            "recbS8zb2m"
        ],
        "双向关联": [
            "recHTLvO7x",
            "recbS8zb2m"
        ],
        "地理位置": "116.397755,39.903179"
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ recordapp.table.record记录更新后的内容
    └ fieldsmap<string, union>成功更新的记录的数据
    └ record_idstring更新记录的 ID
    └ created_byperson该记录的创建人。本接口不返回该参数
      └ idstring用户 ID，ID 类型与 user_id_type 所指定的类型一致
      └ namestring用户的中文名称
      └ en_namestring用户的英文名称
      └ emailstring用户的邮箱
      └ avatar_urlstring头像链接
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ created_timeint该记录的创建时间。本接口不返回该参数
    └ last_modified_byperson该记录最新一次更新的修改人。本接口不返回该参数
      └ idstring用户 ID，ID 类型与 user_id_type 所指定的类型一致
      └ namestring用户的中文名称
      └ en_namestring用户的英文名称
      └ emailstring用户的邮箱
      └ avatar_urlstring头像链接
字段权限要求（满足任一）： contact:user.base:readonly 获取用户基本信息 contact:contact:access_as_app 以应用身份访问通讯录 contact:contact:readonly 读取通讯录 contact:contact:readonly_as_app 以应用身份读取通讯录
    └ last_modified_timeint该记录最近一次的更新时间。本接口不返回该参数
    └ shared_urlstring记录分享链接。本接口不返回该参数，批量获取记录接口将返回该参数
    └ record_urlstring记录链接，本接口不返回该参数，查询记录接口将返回该参数

响应体示例 ​

json
{
    "code": 0,
    "data": {
        "record": {
            "fields": {
                "人员": [
                    {
                        "id": "ou_2910013f1e6456f16a0ce75ede950a0a"
                    },
                    {
                        "id": "ou_e04138c9633dd0d2ea166d79f548ab5d"
                    }
                ],
                "群组": [
                    {
                        "id": "oc_cd07f55f14d6f4a4f1b51504e7e97f48"
                    }
                ],
                "单向关联": [
                    "recHTLvO7x",
                    "recbS8zb2m"
                ],
                "单选": "选项3",
                "双向关联": [
                    "recHTLvO7x",
                    "recbS8zb2m"
                ],
                "地理位置": "116.397755,39.903179",
                "复选框": true,
                "多行文本": "多行文本内容",
                "多选": [
                    "选项1",
                    "选项2"
                ],
                "数字": 100,
                "日期": 1674206443000,
                "条码": "qawqe",
                "电话号码": "13026162666",
                "索引": "索引列多行文本类型",
                "超链接": {
                    "link": "https://www.feishu.cn/product/base",
                    "text": "飞书多维表格官网"
                },
                "附件": [
                    {
                        "file_token": "Vl3FbVkvnowlgpxpqsAbBrtFcrd"
                    }
                ],
                "评分": 3,
                "货币": 3,
                "进度": 0.25
            },
            "id": "reclAqylTN",
            "record_id": "reclAqylTN"
        }
    },
    "msg": "success"
}

错误码 ​

HTTP状态码错误码描述排查建议
2001254000WrongRequestJson请求体错误
2001254001WrongRequestBody请求体错误
2001254002Fail内部错误，请联系技术支持
2001254003WrongBaseTokenapp_token 错误
2001254004WrongTableIdtable_id 错误
2001254005WrongViewIdview_id 错误
2001254006WrongRecordId检查 record_id
2001254007EmptyValue空值
2001254008EmptyView空视图
2001254009WrongFieldId字段 id 错误
2001254010ReqConvError请求错误
4001254015Field types do not match.字段类型不匹配，请检查传入的记录内容是否符合对应字段类型的格式要求
4031254027UploadAttachNotAllowed附件未挂载, 禁止上传
2001254030TooLargeResponse响应体过大
4001254036Base is copying, please try again later.多维表格副本复制中，稍后重试
2001254040BaseTokenNotFoundapp_token 不存在
2001254041TableIdNotFoundtable_id 不存在
2001254042ViewIdNotFoundview_id 不存在
2001254043RecordIdNotFoundrecord_id 不存在
2001254044FieldIdNotFoundfield_id 不存在
2001254045FieldNameNotFound字段名字不存在
2001254060TextFieldConvFail多行文本字段错误
2001254061NumberFieldConvFail数字字段错误
2001254062SingleSelectFieldConvFail单选字段错误，出现这个错误的两种情况为： - 单选字段的值类型不是字符串 string - 单选字段设置的关联选项不支持更新
2001254063MultiSelectFieldConvFail多选字段错误，出现这个错误的两种情况为： - 多选字段的值类型不是字符串 string - 多选字段设置的关联选项不支持更新
2001254064DatetimeFieldConvFail日期字段错误
2001254065CheckboxFieldConvFail复选框字段错误
2001254066UserFieldConvFail人员字段有误。原因可能是： - user_id_type 参数指定的 ID 类型与传入的 ID 类型不匹配 - 传入了不识别的类型或结构，目前只支持填写 id 参数，且需要传入数组 - 跨应用传入了 open_id。如果跨应用传入 ID，建议使用 user_id。不同应用获取的 open_id 不能交叉使用
2001254067LinkFieldConvFail关联字段错误
2001254068URLFieldConvFail超链接字段错误
2001254069AttachFieldConvFail附件字段错误
2001254072InvalidPhoneNumber转换手机号码格式失败，请检查传入的手机号码格式是否正确
4001254074DuplexLinkFieldConvFail参数无效，需要使用字符串数组
2001254100TableExceedLimit数据表或仪表盘数量超限。每个多维表格中，数据表加仪表盘的数量最多为 100 个
2001254101ViewExceedLimit视图数量超限, 限制200个
2001254102FileExceedLimit文件数量超限
2001254103RecordExceedLimit记录数量超限, 限制20,000条
2001254104RecordAddOnceExceedLimit单次添加记录数量超限, 限制500条
2001254105ColumnExceedLimit字段数量超限
2001254106AttachExceedLimit附件过多
2001254112TooManyRequestInSingleBase/
2001254130TooLargeCell格子内容过大
2001254290TooManyRequest请求过快，稍后重试
2001254291Write conflict同一个数据表(table) 不支持并发调用写接口，请检查是否存在并发调用写接口。写接口包括：新增、修改、删除记录；新增、修改、删除字段；修改表单；修改视图等。
2001254301OperationTypeError多维表格未开启高级权限或不支持开启高级权限
2001254303The attachment does not belong to this base.附件无权限
2001255001InternalError内部错误，请联系技术支持
2001255002RpcError内部错误，请联系技术支持
2001255003MarshalError序列化错误，请联系技术支持
2001255004UmMarshalError反序列化错误
2001255005ConvError内部错误，请联系技术支持
5041255040Request timed out, please try again later.请求超时，请进行重试
4001254607Data not ready, please try again later该报错一般是由于前置操作未执行完成，或本次操作数据太大，服务器计算超时导致。遇到该错误码时，建议等待一段时间后重试。通常有以下几种原因： - 编辑操作频繁：开发者对多维表格的编辑操作非常频繁。可能会导致由于等待前置操作处理完成耗时过长而超时的情况。多维表格底层对数据表的处理基于版本维度的串行方式，不支持并发。因此，并发请求时容易出现此类错误，不建议开发者对单个数据表进行并发请求。 - 批量操作负载重：开发者在多维表格中进行批量新增、删除等操作时，如果数据表的数据量非常大，可能会导致单次请求耗时过长，最终导致请求超时。建议开发者适当降低批量请求的 page_size 以减少请求耗时。 - 资源分配与计算开销：资源分配是基于单文档维度的，如果读接口涉及公式计算、排序等计算逻辑，会占用较多资源。例如，并发读取一个文档下的多个数据表也可能导致该文档阻塞。
4031254302Permission denied.无访问权限，常由表格开启了高级权限造成。请确保当前调用身份具有高级权限或多维表格的管理权限： - 对于应用身份，你需要通过云文档网页页面右上方 「...」->「...更多」-> 「添加文档应用」入口添加并授予应用可管理权限，或在高级权限设置中添加一个包含应用的群组，给予这个群读写权限 - 对于用户身份，你需要通过云文档网页的「分享」入口授予用户管理权限 了解更多，参考如何为应用或用户开通云文档权限。
4031254304Permission denied.权限不足。请检查多维表格是否开启了高级权限，如果开启高级权限，调用身份需要有多维表格的可管理权限。详情参考如何为应用或用户开通文档权限
4031254608ReqRecommited请求重复，请检查本次请求的请求参数和上一次是否完全相同

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有