升级旧版表单

升级旧版表单至收集表

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables/:table_id/forms/:form_id/upgrade
HTTP Method	POST
接口频率限制	20 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用	base:form:update 更新表单数据

请求头

名称	类型	必填	描述
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 数据校验规则： - 长度范围：0 ～ 50 字符 示例值："tblz8nadEUdxNMt5"
form_id	string	多维表格中表单的唯一标识。表单也是视图的一种，其获取方式与获取 view_id 相同： - 在多维表格的 URL 地址栏中，form_id 是下图中高亮部分： - 通过列出视图接口获取。暂时无法获取到嵌入到云文档中的多维表格的 form_id 示例值："vew6oMbAa4"

请求体

名称	类型	必填	描述
form_name	string	是	升级后的表单名称 示例值："文档问题反馈" 数据校验规则： - 长度范围：1 ～ 100 字符 - 正则校验：^[^[\]]+$
display_mode	string	是	表单布局模式。 示例值："one_question_per_page" 可选值有： - traditional: 传统布局 - one_question_per_page: 一页一题布局

请求体示例

{
    "form_name": "文档问题反馈",
    "display_mode": "one_question_per_page"
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ form	upgraded_form	升级后的表单
└ id	string	升级后的表单ID

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "form": {
            "id": "vew6oMbAa4"
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1254000	WrongRequestJson	请求体错误，请检查请求体的格式是否符合接口要求（如JSON格式是否正确）
400	1254001	WrongRequestBody	请求体错误，请检查请求体的格式是否符合接口要求（如JSON格式是否正确）
500	1254002	Fail	内部错误，请联系技术支持
400	1254003	WrongBaseToken	请检查app_token是否正确，获取方式参考多维表格 app_token 获取方式
400	1254004	WrongTableId	请检查table_id是否正确，获取方式参考列出数据表接口或多维表格URL
400	1254005	WrongViewId	view_id 错误，请检查view_id是否正确，获取方式参考列出视图接口或多维表格URL
400	1254008	EmptyView	空视图，请确保视图中存在数据后再操作
400	1254019	InvalidViewType	视图类型无效，请传入正确的视图类型（如表格视图、看板视图等）
400	1254036	Bitable is copying, please try again later.	复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
404	1254040	BaseTokenNotFound	app_token 不存在，请检查传入的 app_token 是否正确或是否已创建该多维表格 App
404	1254041	TableIdNotFound	table_id 不存在，请检查传入的 table_id 是否正确或是否已创建该数据表
404	1254042	ViewIdNotFound	view_id 不存在，请检查传入的 view_id 是否正确或是否已创建该视图
400	1254124	The name of the new form is empty	新表单名称不允许为空
400	1254125	The name of the new form is invalid.	新表单名称无效，请检查名称是否符合长度（1-100字符）和正则（^[^[]]+$）要求
400	1254126	The display mode of the new form is invalid.	新表单的布局模式无效，请传入正确的布局模式（traditional 或 one_question_per_page）
400	1254127	The name of the new form is duplicated.	新表单的名称与已有视图名称重复，请修改表单名称为唯一值
400	1254128	The form is already a new version, no upgrade required.	已经是新版表单，无需升级
500	1254200	Something went wrong	内部错误，请联系技术支持
400	1254290	TooManyRequest	请求过快，稍后重试
400	1254291	Write conflict	同一个数据表(table) 不支持并发调用写接口，请检查是否存在并发调用写接口。写接口包括：新增、修改、删除记录；新增、修改、删除字段；修改表单；修改视图；升级表单等。
403	1254302	Permission denied.	调用身份缺少多维表格的高级权限。你需要为调用身份授予高级权限： - 对用户授予高级权限，你需要在多维表格页面右上方 分享 入口为当前用户添加可管理权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组, 给予这个群自定义的读写等权限。
403	1254304	You are not authorized to perform this operation.	仅企业版和旗舰版飞书支持行列权限
403	1254305	PermControl	本次操作受到限制，例如租户私密等级限制、wiki空间权限限制等，请联系租户管理员确认是否有相关权限或限制设置
500	1254607	Data not ready, please try again later	该报错一般是由于前置操作未执行完成，或本次操作数据太大，服务器计算超时导致。遇到该错误码时，建议等待一段时间后重试。通常有以下几种原因： - 编辑操作频繁：开发者对多维表格的编辑操作非常频繁。可能会导致由于等待前置操作处理完成耗时过长而超时的情况。多维表格底层对数据表的处理基于版本维度的串行方式，不支持并发。因此，并发请求时容易出现此类错误，不建议开发者对单个数据表进行并发请求。 - 批量操作负载重：开发者在多维表格中进行批量新增、删除等操作时，如果数据表的数据量非常大，可能会导致单次请求耗时过长，最终导致请求超时。建议开发者适当降低批量请求的 page_size 以减少请求耗时。 - 资源分配与计算开销：资源分配是基于单文档维度的，如果读接口涉及公式计算、排序等计算逻辑，会占用较多资源。例如，并发读取一个文档下的多个数据表也可能导致该文档阻塞。
500	1255001	InternalError	内部错误，请联系技术支持
500	1255002	RpcError	内部错误，请联系技术支持
500	1255003	MarshalError	序列化错误，请联系技术支持
500	1255004	UmMarshalError	反序列化错误，请联系技术支持
504	1255040	Request timeout	请稍后重试