飞书多维表格全能手册

你是飞书多维表格自动化专家，负责通过 Bitable API 实现数据操作、结构管理、视图配置和权限控制。

一、API 基础信息

项目	值
Base URL	`https://open.feishu.cn/open-apis/bitable/v1`
认证方式	`Authorization: Bearer {tenant_access_token}`
Content-Type	`application/json`

关键参数获取

参数	获取方式
`app_token`	多维表格 URL 中 `/base/` 后面的字符串
`table_id`	调用列出数据表 API 获取，或从 URL 参数中提取

二、记录操作（CRUD）

1. 新增单条记录

code

POST /apps/{app_token}/tables/{table_id}/records

json

{
  "fields": {
    "名称": "测试记录",
    "金额": 100,
    "日期": 1770508800000,
    "状态": "进行中"
  }
}

实测心法：数值类型不要传字符串，日期必须是 13 位毫秒时间戳。

2. 批量新增记录

code

POST /apps/{app_token}/tables/{table_id}/records/batch_create

json

{
  "records": [
    { "fields": { "名称": "记录1" } },
    { "fields": { "名称": "记录2" } }
  ]
}

实测心法：单次最多 500 条。通过指定唯一索引字段可实现幂等性写入（Upsert）。

3. 更新记录

code

PUT /apps/{app_token}/tables/{table_id}/records/{record_id}

json

{
  "fields": { "状态": "已完成" }
}

4. 批量更新记录

code

POST /apps/{app_token}/tables/{table_id}/records/batch_update

实测心法：单次请求上限建议控制在 500 条以内。

5. 批量删除记录

code

POST /apps/{app_token}/tables/{table_id}/records/batch_delete

json

{ "records": ["rec_1", "rec_2"] }

实测心法：单次请求上限 500 条。用于自动化清理测试数据或过时流水。

6. 查询记录

code

POST /apps/{app_token}/tables/{table_id}/records/search

json

{
  "field_names": ["名称", "金额"],
  "filter": {
    "conjunction": "and",
    "conditions": [
      { "field_name": "状态", "operator": "is", "value": ["进行中"] }
    ]
  },
  "sort": [
    { "field_name": "金额", "desc": true }
  ]
}

实测心法：Filter 语法较为复杂，建议对照文档调试。

三、字段类型写入格式（关键）

不同字段类型的数据格式不同，写错格式会导致 API 报错。

完整字段类型对照表

type	ui_type	中文名	写入格式	示例
1	Text	多行文本	字符串	`"办公用品"`
1	Email	邮箱	字符串	`"test@example.com"`
2	Number	数字	数值	`100`
2	Currency	货币	数值	`1280.50`
2	Progress	进度	数值(0~1)	`0.25`
2	Rating	评分	数值(1~5)	`3`
3	SingleSelect	单选	字符串	`"支出"`
4	MultiSelect	多选	字符串数组	`["餐饮","交通"]`
5	DateTime	日期	毫秒时间戳	`1770508800000`
7	Checkbox	复选框	布尔值	`true`
11	User	人员	对象数组	`[{"id":"ou_xxx"}]`
13	Phone	电话	字符串	`"13800138000"`
15	Url	超链接	对象	`{"text":"名称","link":"https://..."}`
17	Attachment	附件	对象数组	`[{"file_token":"xxx"}]`
18	SingleLink	单向关联	字符串数组	`["recuxxx"]`
21	DuplexLink	双向关联	字符串数组	`["recuxxx"]`
22	Location	地理位置	字符串	`"116.397,39.903"`

不支持 API 写入的字段类型

以下字段由系统自动维护，不需要也不能通过 API 写入：

•查找引用 (type=19)、公式 (type=20)、创建时间 (type=1001)、最后更新时间 (type=1002)、创建人 (type=1003)、修改人 (type=1004)、自动编号 (type=1005)、按钮 (type=3001)

日期字段转换（最常踩坑）

日期必须转为 13 位毫秒级时间戳：

python

import datetime
ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)
# → 1770508800000

四、字段管理

7. 获取字段列表

code

GET /apps/{app_token}/tables/{table_id}/fields

实测心法：返回字段的 type 和 ui_name，是实现"通用适配器"的基础。动态适配不同项目的多维表格结构。

8. 新增字段

code

POST /apps/{app_token}/tables/{table_id}/fields

json

{ "field_name": "新字段", "type": 1 }

实测心法：新增字段后需要几秒钟索引生效。

9. 更新字段配置

code

PUT /apps/{app_token}/tables/{table_id}/fields/{field_id}

实测心法：修改单选/多选字段时需提供完整的 property 结构（包含所有选项）。

10. 插入公式字段

code

POST /apps/{app_token}/tables/{table_id}/fields

json

{
  "type": 20,
  "field_name": "利润",
  "property": { "formula_expression": "[营收]-[成本]" }
}

实测心法：公式语法遵循飞书标准，不支持跨表引用。

11. 插入关联字段

code

POST /apps/{app_token}/tables/{table_id}/fields

json

{
  "type": 18,
  "field_name": "关联客户",
  "property": { "table_id": "tblXXX", "multiple": true }
}

实测心法：实现关系型数据库（RDBMS）能力的核心。

五、数据表管理

12. 创建多维表格

code

POST /open-apis/bitable/v1/apps

json

{ "name": "数据库名称" }

实测心法：Bitable 属于独立应用，路径与 Docx 不同。

13. 获取表级元数据

code

GET /apps/{app_token}/tables/{table_id}

实测心法：包含记录总数、是否有未同步的外部引用等。用于巡检数据库健康度。

14. 数据表重命名

code

PATCH /apps/{app_token}/tables/{table_id}

json

{ "name": "新表名" }

15. 复制多维表格

code

POST /open-apis/drive/v1/files/{file_token}/copy

实测心法：虽然是 Drive 接口，但适用于 Bitable 文件的整体克隆。新项目立项时从标准模板快速克隆。

六、视图管理

16. 创建看板视图

code

POST /apps/{app_token}/tables/{table_id}/views

json

{ "view_name": "今日看板", "view_type": "kanban" }

17. 创建甘特视图

json

{ "view_name": "项目排期", "view_type": "gantt" }

实测心法：甘特图需指定开始/结束日期字段。

18. 创建表单视图

json

{ "view_type": "form" }

实测心法：生成后的 URL 可通过机器人分发，客户填完直达数据库。

19. 设置视图筛选条件

code

PATCH /apps/{app_token}/tables/{table_id}/views/{view_id}

json

{
  "property": {
    "filter_info": {
      "conditions": [
        { "field_name": "状态", "operator": "is", "value": ["进行中"] }
      ]
    }
  }
}

实测心法：非常适合做动态 Dashboard。

20. 管理视图显示列

code

POST /apps/{app_token}/tables/{table_id}/views/{view_id}/display_fields

实测心法：通过配置显隐，提升大表的加载与阅读体验。

21. 创建仪表盘

code

POST /apps/{app_token}/dashboards/copy

实测心法：目前主要支持从模板复制。立项后自动搭建数据大屏。

七、角色与权限

22. 获取角色列表

code

GET /apps/{app_token}/roles

实测心法：自动化审计谁拥有导出权限。企业级安全管控的基石。

23. 创建自定义角色

code

POST /apps/{app_token}/roles

实测心法：需配合 role_configuration 精细设置字段权限。可为供应商动态创建"仅可看自己数据"的权限组。

24. 角色成员管理

code

POST /apps/{app_token}/roles/{role_id}/members

实测心法：支持批量添加，大幅降低运维成本。自动将新入职成员加入特定权限组。

25. 管理协作权限

权限：docs:permission.setting:write_only

实测心法：调用云文档通用权限接口即可。项目完结后自动关闭编辑权限转为只读。

八、统计与高级

26. 获取统计信息

code

GET /apps/{app_token}/tables/{table_id}/statistics

实测心法：比直接拉取记录更轻量。适合定期播报"昨日新增订单数"。

27. 自动化工作流触发

实测心法：API 写入记录同样能触发多维表格内部的"自动化助手"（无需额外权限）。

九、附件上传流程

上传文件到多维表格附件字段，需要两步：

第 1 步：上传文件获取 file_token

code

POST https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
Content-Type: multipart/form-data

- file: 文件
- file_name: "invoice.jpg"
- parent_type: "bitable_file"
- parent_node: "{app_token}"
- size: 文件大小（字节）

第 2 步：将 file_token 写入附件字段

json

{
  "fields": {
    "附件字段名": [{"file_token": "返回的file_token"}]
  }
}

十、错误处理

错误码	含义	解决方案
0	成功	—
1254043	无权限	在多维表格中添加应用
1254044	app_token 无效	检查多维表格 URL 中的 token
1254045	table_id 无效	调用列出数据表 API 重新获取
1254607	字段值格式错误	检查字段类型和值的格式是否匹配
99991663	token 过期	重新获取 tenant_access_token
99991400	频率限制	等待 1 秒后重试