更新表单元数据

更新表单视图中的元数据，包括表单名称、描述、是否共享等。

Tip: 表单视图是多维表格的一种视图类型。每个表单都有唯一标识 form_id，即当前视图的 view_id。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/forms/:form_id
HTTP Method	PATCH
接口频率限制	10 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	base:form:update 更新表单数据 bitable:app 查看、评论、编辑和管理多维表格

请求头

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

路径参数

名称	类型	描述
app_token	string	多维表格 App 的唯一标识。不同形态的多维表格，其 app_token 的获取方式不同： - 如果多维表格的 URL 以 ==feishu.cn/base== 开头，该多维表格的 app_token 是下图高亮部分： - 如果多维表格的 URL 以 ==feishu.cn/wiki== 开头，你需调用知识库相关获取知识空间节点信息接口获取多维表格的 app_token。当 obj_type 的值为 bitable 时，obj_token 字段的值才是多维表格的 app_token。 了解更多，参考多维表格 app_token 获取方式。 示例值："bascnv1jIEppJdTCn3jOosabcef"
table_id	string	多维表格数据表的唯一标识。获取方式： - 你可通过多维表格 URL 获取 table_id，下图高亮部分即为当前数据表的 table_id - 也可通过列出数据表接口获取 table_id 示例值："tblz8nadEUdxNMt5"
form_id	string	多维表格中表单的唯一标识。表单也是视图的一种，其获取方式与获取 view_id 相同： - 在多维表格的 URL 地址栏中，form_id 是下图中高亮部分： - 通过列出视图接口获取。暂时无法获取到嵌入到云文档中的多维表格的 form_id 示例值："vew6oMbAa4"

请求体

名称	类型	必填	描述
name	string	否	表单名称 示例值："文档问题反馈"
description	string	否	表单描述 示例值："请详细描述开发中遇到的问题，并附上问题截图"
shared	boolean	否	是否开启表单分享，使表单支持填写。可选值： - true：支持填写 - false：不支持填写 示例值：true
shared_limit	string	否	分享表单范围限制。当 shared 参数为 true 时支持传入该字段 示例值："tenant_editable" 可选值有： - off: 仅邀请的人可填写 - tenant_editable: 组织内获得链接的人可填写 - anyone_editable: 互联网上获得链接的人可填写
submit_limit_once	boolean	否	是否将填写次数限制为一次。可选值： - true：设置表单仅支持填写一次 - false：不限制表单填写次数 示例值：true

请求体示例

{
    "name": "文档问题反馈",
    "description": "请详细描述开发中遇到的问题，并附上问题截图",
    "shared": true,
    "shared_limit": "tenant_editable",
    "submit_limit_once": true
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ form	app.table.form	表单元数据信息
└ name	string	表单名称
└ description	string	表单描述
└ shared	boolean	是否开启共享
└ shared_url	string	填写表单的 URL 链接。若开启共享，将返回该值
└ shared_limit	string	分享范围限制 可选值有： - off: 仅邀请的人可填写 - tenant_editable: 组织内获得链接的人可填写 - anyone_editable: 互联网上获得链接的人可填写
└ submit_limit_once	boolean	填写次数是否限制为一次

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "form": {
            "name": "表单",
            "description": "表单描述",
            "shared": true,
            "shared_url": "https://example.feishu.cn/share/base/shrcnCy1KAlpahNotmhRn1abcde",
            "shared_limit": "tenant_editable",
            "submit_limit_once": true
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1254000	WrongRequestJson	请求体错误
400	1254001	WrongRequestBody	请求体错误
400	1254002	Fail	导致报 1254002 错误码的场景较多，请参考以下排查建议排查： - 如果日志内容显示 changeset size exceed the limit, len:xxxxx，表示单次操作的内容变更较大，你需要在单次操作中减少数据量 - 如果日志内容显示 lock not obtained 或 data not ready，表示并发调用接口导致抢锁失败出错。你需控制请求间隔，稍后重试 - 如果在知识库（wiki）中创建多维表格，请检查你是否使用了知识库创建知识空间节点接口创建多维表格。在此场景下不能使用创建多维表格接口 - 请检查接口参数是否有误。例如，在分页查询多维表格时，传递了无效的 page_token，或传递了错误的数据表的 table_id - 如果该报错偶尔发生，可能是服务器超时或不稳定，请重试解决
400	1254003	WrongBaseToken	app_token 错误
400	1254004	WrongTableId	table_id 错误
400	1254005	WrongViewId	view_id 错误
400	1254006	WrongRecordId	检查 record_id
400	1254007	EmptyValue	空值
400	1254008	EmptyView	空视图
400	1254009	WrongFieldId	字段 id 错误
400	1254010	ReqConvError	请求错误
400	1254016	InvalidSort	Sort参数错误
400	1254018	InvalidFilter	filter 参数错误。请参考记录过滤参数填写指南了解如何填写 filter 参数。
400	1254019	InvalidViewType	视图类型无效
400	1254020	ViewNameDuplicated	视图名重复
400	1254021	EmptyViewName	视图名为空
400	1254022	InvalidViewName	视图名无效
400	1254030	TooLargeResponse	响应体过大
404	1254040	BaseTokenNotFound	app_token 不存在
404	1254041	TableIdNotFound	table_id 不存在
404	1254042	ViewIdNotFound	view_id 不存在
404	1254043	RecordIdNotFound	record_id 不存在
404	1254044	FieldIdNotFound	field_id 不存在
404	1254045	FieldNameNotFound	字段名称不存在。请检查: - 接口中字段名称和多维表格中的字段名称是否完全匹配。如果难以排查，建议你调用列出字段接口获取字段名称，因为根据表格页面的 UI 名称可能会忽略空格、换行或特殊符号等差异。 - 表格是否开启了高级权限但调用身份缺少对应字段的权限。你需要为调用身份授予高级权限： - 对用户授予高级权限，你需要在多维表格页面右上方 分享 入口为当前用户添加可管理权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组, 给予这个群自定义的读写等权限。
404	1254049	FormFieldNotFound	form_field_id 不存在
400	1254060	TextFieldConvFail	多行文本字段错误
400	1254061	NumberFieldConvFail	数字字段错误
400	1254062	SingleSelectFieldConvFail	单选字段错误
400	1254063	MultiSelectFieldConvFail	多选字段错误
400	1254064	DatetimeFieldConvFail	日期字段错误
400	1254065	CheckboxFieldConvFail	复选框字段错误
400	1254066	UserFieldConvFail	人员字段有误。原因可能是： - user_id_type 参数指定的 ID 类型与传入的 ID 类型不匹配 - 传入了不识别的类型或结构，目前只支持填写 id 参数，且需要传入数组 - 跨应用传入了 open_id。如果跨应用传入 ID，建议使用 user_id。不同应用获取的 open_id 不能交叉使用
400	1254067	LinkFieldConvFail	关联字段错误
400	1254100	TableExceedLimit	数据表或仪表盘数量超限。每个多维表格中，数据表加仪表盘的数量最多为 100 个
400	1254101	ViewExceedLimit	视图数量超限, 限制200个
400	1254103	RecordExceedLimit	记录数量超限, 限制20,000条
400	1254104	RecordAddOnceExceedLimit	单次添加记录数量超限, 限制500条
400	1254130	TooLargeCell	格子内容过大
429	1254290	TooManyRequest	请求过快，稍后重试
400	1254291	Write conflict	同一个数据表(table) 不支持并发调用写接口，请检查是否存在并发调用写接口。写接口包括：新增、修改、删除记录；新增、修改、删除字段；修改表单；修改视图等。
400	1254301	OperationTypeError	多维表格未开启高级权限或不支持开启高级权限
403	1254302	Permission denied.	调用身份缺少多维表格的高级权限。你需要为调用身份授予高级权限： - 对用户授予高级权限，你需要在多维表格页面右上方 分享 入口为当前用户添加可管理权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组, 给予这个群自定义的读写等权限。
400	1255001	InternalError	内部错误，请联系技术支持
400	1255002	RpcError	内部错误，请联系技术支持
400	1255003	MarshalError	序列化错误，请联系技术支持
400	1255004	UmMarshalError	反序列化错误
400	1255005	ConvError	内部错误，请联系技术支持
504	1255040	请求超时	进行重试
400	1254036	Base is copying, please try again later.	复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
500	1254200	internal error	内部错误，请联系技术支持
403	1254608	Same API requests are submitted repeatedly.	基于同一个多维表格版本重复提交了更新请求，常见于并发或时间间隔极短的请求，例如并发将一个视图的信息更新为相同的内容。建议稍后重试
403	1254305	PermControl	本次操作受到限制，例如租户私密等级限制、wiki空间权限限制等
400	1254607	Data not ready, please try again later	该报错一般是由于前置操作未执行完成，或本次操作数据太大，服务器计算超时导致。遇到该错误码时，建议等待一段时间后重试。通常有以下几种原因： - 编辑操作频繁：开发者对多维表格的编辑操作非常频繁。可能会导致由于等待前置操作处理完成耗时过长而超时的情况。多维表格底层对数据表的处理基于版本维度的串行方式，不支持并发。因此，并发请求时容易出现此类错误，不建议开发者对单个数据表进行并发请求。 - 批量操作负载重：开发者在多维表格中进行批量新增、删除等操作时，如果数据表的数据量非常大，可能会导致单次请求耗时过长，最终导致请求超时。建议开发者适当降低批量请求的 page_size 以减少请求耗时。 - 资源分配与计算开销：资源分配是基于单文档维度的，如果读接口涉及公式计算、排序等计算逻辑，会占用较多资源。例如，并发读取一个文档下的多个数据表也可能导致该文档阻塞。
403	1254304	You are not authorized to perform this operation.	仅企业版和旗舰版飞书支持行列权限