feishu_bitable/docs/新增一个数据表.md

新增一个数据表

新增一个数据表，支持传入数据表名称、视图名称和字段。

前提条件

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

使用限制

每个多维表格中，数据表与仪表盘的总数量上限为 100。

请求

基本
HTTP URL	https://open.feishu.cn/open-apis/bitable/v1/apps/:app_token/tables
HTTP Method	POST
接口频率限制	10 次/秒
支持的应用类型	Custom App、Store App
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	新增数据表(base:table:create) 查看、评论、编辑和管理多维表格(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 获取方式。 示例值："appbcbWCzen6D8dezhoCH2RpMAh" 数据校验规则： - 最小长度：1 字符

请求体

名称	类型	必填	描述
table	req_table	否	数据表
name	string	否	数据表名称。该字段必填。 注意： - 名称中的首尾空格将会被默认去除 - 数据表名称不可以包含 / \ ? * : [ ] 等特殊字符 示例值："一个新的数据表" 数据校验规则： - 长度范围：1 ～ 100 字符
default_view_name	string	否	默认表格视图的名称。 注意： - 名称中的首尾空格将会被去除 - 名称中不允许包含 [ ] 两个字符 示例值："表格视图"
fields	app.table.create_header[]	否	数据表的初始字段。了解如何填写字段，参考字段编辑指南。 注意： - 如果传入了 default_view_name 字段，则必须传入 fields 字段 - 如果不传 default_view_name 字段，则 fields 字段为可选字段 - 若 default_view_name 字段和 fields 字段都不传，将会创建一个仅包含索引字段的空数据表。 - 数据表的第一个字段为索引字段。索引字段仅支持以下类型： - 1：多行文本 - 2：数字 - 5：日期 - 13：电话号码 - 15：超链接 - 20：公式 - 22：地理位置 数据校验规则： - 长度范围：1 ～ 300
field_name	string	是	字段名称 示例值："问题描述"
type	int	是	字段类型。不支持新增 19 查找引用字段类型。 示例值：1 可选值有： - 1：文本 - 2：数字 - 3：单选 - 4：多选 - 5：日期 - 7：复选框 - 11：人员 - 13：电话号码 - 15：超链接 - 17：附件 - 18：单向关联 - 20：公式 - 21：双向关联 - 22：地理位置 - 23：群组 - 1001：创建时间 - 1002：最后更新时间 - 1003：创建人 - 1004：修改人 - 1005：自动编号
ui_type	string	否	字段在界面上的展示类型，例如 Progress 进度字段是数字的一种展示形态 示例值："Progress" 可选值有： - Text：文本 - Barcode：条码 - Number：数字 - Progress：进度 - Currency：货币 - Rating：评分 - SingleSelect：单选 - MultiSelect：多选 - DateTime：日期 - Checkbox：复选框 - User：人员 - GroupChat：群组 - Phone：电话号码 - Url：超链接 - Attachment：附件 - SingleLink：单向关联 - Formula：公式 - DuplexLink：双向关联 - Location：地理位置 - CreatedTime：创建时间 - ModifiedTime：最后更新时间 - CreatedUser：创建人 - ModifiedUser：修改人 - AutoNumber：自动编号
property	app.table.field.property	否	字段属性
options	app.table.field.property.option[]	否	单选、多选字段的选项信息
name	string	否	选项名 示例值："红色"
id	string	否	选项 ID，创建时不可指定 ID 示例值："optKl35lnG"
color	int	否	选项颜色，详情参考字段编辑指南。 示例值：0 数据校验规则： - 取值范围：0 ～ 54
formatter	string	否	数字、公式字段的显示格式。详情参考字段编辑指南。 示例值："0"
date_formatter	string	否	日期、创建时间、最后更新时间字段的显示格式。默认为 "yyyy/MM/dd"，详情参考字段编辑指南。 示例值："2021/01/30"
auto_fill	boolean	否	日期字段中新纪录自动填写创建时间。默认为 false 示例值：false
multiple	boolean	否	人员字段中允许添加多个成员，单向关联、双向关联中允许添加多个记录 示例值：false
table_id	string	否	单向关联、双向关联字段中关联的数据表的id 示例值："tblsRc9GRRXKqhvW"
table_name	string	否	单向关联、双向关联字段中关联的数据表的名字 示例值："table2"
back_field_name	string	否	双向关联字段中关联的数据表中对应的双向关联字段的名字 示例值："table1-双向关联"
auto_serial	app.field.property.auto_serial	否	自动编号类型
type	string	是	自动编号类型 示例值："auto_increment_number" 可选值有： - custom：自定义编号 - auto_increment_number：自增数字
options	app.field.property.auto_serial.options[]	否	自动编号规则列表
type	string	是	自动编号的可选规则项类型 示例值："created_time" 可选值有： - system_number：自增数字位,value范围1-9 - fixed_text：固定字符，最大长度：20 - created_time：创建时间，支持格式 "yyyyMMdd"、"yyyyMM"、"yyyy"、"MMdd"、"MM"、"dd"
value	string	是	与自动编号的可选规则项类型相对应的取值 示例值："yyyyMMdd"
location	app.field.property.location	否	地理位置输入方式
input_type	string	是	地理位置输入限制 示例值："not_limit" 可选值有： - only_mobile：只允许移动端上传 - not_limit：无限制
formula_expression	string	否	公式字段的表达式 示例值："bitable::$table[tblNj92WQBAasdEf].$field[fldMV60rYs]*2"
allowed_edit_modes	allowed_edit_modes	否	字段支持的编辑模式
manual	boolean	否	是否允许手动录入 示例值：true
scan	boolean	否	是否允许移动端录入 示例值：true
min	number(float)	否	进度、评分等字段的数据范围最小值 示例值：0
max	number(float)	否	进度、评分等字段的数据范围最大值 示例值：10
range_customize	boolean	否	进度等字段是否支持自定义范围 示例值：true
currency_code	string	否	货币币种 示例值："CNY"
rating	rating	否	评分字段的相关设置
symbol	string	否	评分字段的符号展示 示例值："star"
description	app.table.field.description	否	字段的描述
disable_sync	boolean	否	是否禁止同步，如果为true，表示禁止同步该描述内容到表单的问题描述 示例值：true 默认值：true
text	string	否	字段描述内容，支持换行\n 示例值："请按 name_id 格式填写\n例如：“Alice_20202020”"

请求体示例

{
  "table": {
    "name": "数据表名称",
    "default_view_name": "默认的表格视图",
    "fields": [
      {
        "field_name": "索引字段",
        "type": 1
      },
      {
        "field_name": "单选",
        "type": 3,
        "ui_type": "SingleSelect",
        "property": {
          "options": [
            {
              "name": "Enabled",
              "color": 0
            },
            {
              "name": "Disabled",
              "color": 1
            },
            {
              "name": "Draft",
              "color": 2
            }
          ]
        }
      }
    ]
  }
}

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	-	-
table_id	string	多维表格数据表的 ID
default_view_id	string	默认表格视图的 ID。该字段仅在请求参数中填写了default_view_name 或 fields 字段才会返回
field_id_list	string[]	数据表初始字段的 ID 列表，该字段仅在请求参数中填写了 fields 才会返回

响应体示例

{
	"code": 0,
	"msg": "success",
	"data": {
		"table_id": "tblDBTWm6Es84d8c",
		"default_view_id": "vewUuKOz2R",
		"field_id_list": [
			"fldhr2hBEA"
		]
	}
}

错误码

HTTP状态码	错误码	描述	排查建议
200	1254000	WrongRequestJson	请求体错误
200	1254001	WrongRequestBody	请求体错误。请检查请求体中是否已传入所有必填参数
200	1254002	Fail	内部错误，请联系技术支持
200	1254003	WrongBaseToken	app_token 错误
200	1254004	WrongTableId	table_id 错误
200	1254007	EmptyValue	空值
200	1254008	EmptyView	空视图
200	1254009	WrongFieldId	字段 id 错误
200	1254010	ReqConvError	请求错误
400	1254012	NotSupportFieldOrView	不支持的字段或视图。注意数据表的初始索引字段仅支持以下类型： - 1：多行文本 - 2：数字 - 5：日期 - 13：电话号码 - 15：超链接 - 20：公式 - 22：地理位置
200	1254013	TableNameDuplicated	表名重复
400	1254014	FieldNameDuplicated	字段名重复
400	1254021	EmptyViewName	视图名为空
400	1254022	InvalidViewName	视图名无效
400	1254029	InvalidFieldName	字段名无效
200	1254030	TooLargeResponse	响应体过大
200	1254036	Base is copying, please try again later.	复制多维表格为异步操作，该错误码表示当前多维表格仍在复制中，在复制期间无法操作当前多维表格。需要等待复制完成后再操作
200	1254040	BaseTokenNotFound	app_token 不存在
200	1254041	TableIdNotFound	table_id 不存在
200	1254044	FieldIdNotFound	field_id 不存在
200	1254060	TextFieldConvFail	多行文本字段错误
200	1254061	NumberFieldConvFail	数字字段错误
200	1254062	SingleSelectFieldConvFail	单选字段错误
200	1254063	MultiSelectFieldConvFail	多选字段错误
200	1254064	DatetimeFieldConvFail	日期字段错误
200	1254065	CheckboxFieldConvFail	复选框字段错误
200	1254066	UserFieldConvFail	人员字段有误。原因可能是： - user_id_type 参数指定的 ID 类型与传入的 ID 类型不匹配 - 传入了不识别的类型或结构，目前只支持填写 id 参数，且需要传入数组 - 跨应用传入了 open_id。如果跨应用传入 ID，建议使用 user_id。不同应用获取的 open_id 不能交叉使用 - 若想对人员字段传空，可传 null
200	1254067	LinkFieldConvFail	关联字段错误
200	1254100	TableExceedLimit	数据表或仪表盘数量超限。每个多维表格中，数据表加仪表盘的数量最多为 100 个
200	1254101	ViewExceedLimit	视图数量超限, 限制200个
200	1254130	TooLargeCell	格子内容过大
200	1254290	TooManyRequest	请求过快，稍后重试
200	1254291	Write conflict	同一个数据表(table) 不支持并发调用写接口，请检查是否存在并发调用写接口。写接口包括：新增、修改、删除记录；新增、修改、删除字段；修改表单；修改视图等。
200	1254301	OperationTypeError	多维表格未开启高级权限或不支持开启高级权限
403	1254302	Permission denied.	调用身份缺少多维表格的高级权限。你需要为调用身份授予高级权限： - 对用户授予高级权限，你需要在多维表格页面右上方 分享 入口为当前用户添加可管理权限。 - 对应用授予高级权限，你需通过多维表格页面右上方 「...」 -> 「...更多」 ->「添加文档应用」 入口为应用添加可管理权限。 注意： 在 添加文档应用 前，你需确保目标应用至少开通了一个多维表格的 API 权限。否则你将无法在文档应用窗口搜索到目标应用。 - 你也可以在 多维表格高级权限设置 中添加用户或一个包含应用的群组, 给予这个群自定义的读写等权限。
400	1254607	Data not ready, please try again later	该报错一般是由于前置操作未执行完成，或本次操作数据太大，服务器计算超时导致。遇到该错误码时，建议等待一段时间后重试。通常有以下几种原因： - 编辑操作频繁：开发者对多维表格的编辑操作非常频繁。可能会导致由于等待前置操作处理完成耗时过长而超时的情况。多维表格底层对数据表的处理基于版本维度的串行方式，不支持并发。因此，并发请求时容易出现此类错误，不建议开发者对单个数据表进行并发请求。 - 批量操作负载重：开发者在多维表格中进行批量新增、删除等操作时，如果数据表的数据量非常大，可能会导致单次请求耗时过长，最终导致请求超时。建议开发者适当降低批量请求的 page_size 以减少请求耗时。 - 资源分配与计算开销：资源分配是基于单文档维度的，如果读接口涉及公式计算、排序等计算逻辑，会占用较多资源。例如，并发读取一个文档下的多个数据表也可能导致该文档阻塞。
200	1255001	InternalError	内部错误，请联系技术支持
200	1255002	RpcError	内部错误，请联系技术支持
200	1255003	MarshalError	序列化错误，请联系技术支持
200	1255004	UmMarshalError	反序列化错误
200	1255005	ConvError	服务内部错误，请联系技术支持