陌讯skills聚合平台

feishu-bitable

📁 alextangson/feishu_skills 📅 9 days ago
26
总安装量
26
周安装量
#14065
全站排名
安装命令
npx skills add https://github.com/alextangson/feishu_skills --skill feishu-bitable

Agent 安装分布

gemini-cli 26
github-copilot 26
codex 26
amp 26
kimi-cli 26
cursor 26

Skill 文档

飞书多维表格全能手册

你是飞书多维表格自动化专家，负责通过 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. 新增单条记录

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

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

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

2. 批量新增记录

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

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

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

3. 更新记录

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

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

4. 批量更新记录

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

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

5. 批量删除记录

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

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

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

6. 查询记录

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

{
  "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 位毫秒级时间戳：

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

四、字段管理

7. 获取字段列表

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

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

8. 新增字段

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

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

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

9. 更新字段配置

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

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

10. 插入公式字段

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

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

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

11. 插入关联字段

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

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

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

五、数据表管理

12. 创建多维表格

POST /open-apis/bitable/v1/apps

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

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

13. 获取表级元数据

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

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

14. 数据表重命名

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

{ "name": "新表名" }

15. 复制多维表格

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

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

六、视图管理

16. 创建看板视图

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

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

17. 创建甘特视图

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

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

18. 创建表单视图

{ "view_type": "form" }

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

19. 设置视图筛选条件

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

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

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

20. 管理视图显示列

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

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

21. 创建仪表盘

POST /apps/{app_token}/dashboards/copy

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

七、角色与权限

22. 获取角色列表

GET /apps/{app_token}/roles

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

23. 创建自定义角色

POST /apps/{app_token}/roles

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

24. 角色成员管理

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

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

25. 管理协作权限

权限：docs:permission.setting:write_only

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

八、统计与高级

26. 获取统计信息

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

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

27. 自动化工作流触发

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

九、附件上传流程

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

第 1 步：上传文件获取 file_token

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 写入附件字段

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

十、错误处理

错误码 含义 解决方案
0 成功 —
1254043 无权限 在多维表格中添加应用
1254044 app_token 无效 检查多维表格 URL 中的 token
1254045 table_id 无效 调用列出数据表 API 重新获取
1254607 字段值格式错误 检查字段类型和值的格式是否匹配
99991663 token 过期 重新获取 tenant_access_token
99991400 频率限制 等待 1 秒后重试
GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。