feishu-bitable

飞书多维表格

通过 Bitable API 操作数据、字段、视图和权限。

Base URL: https://open.feishu.cn/open-apis/bitable/v1

认证与 Token 获取

从 feishu_skills 根目录执行共享脚本：

TOKEN="$(./scripts/get_feishu_token.sh)"

请求头统一使用 Authorization: Bearer ${TOKEN}。

如果业务接口返回 token 无效、过期或 401，强制刷新后仅重试一次原请求：

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

环境变量:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

本地缓存: ./.feishu_token_cache.json（未过期直接复用，默认提前 5 分钟刷新）

关键参数:

• app_token: 多维表格 URL 中 /base/ 后的字符串
• table_id: 调用列表 API 获取

记录操作

分页查询全部记录（单次最多 500 条，循环直到 has_more: false）：

请求示例:

⚠️ 数值不要传字符串，日期必须是 13 位毫秒时间戳。

字段类型格式

不支持 API 写入: 公式、查找引用、创建时间、修改人、自动编号

日期格式转换:

字段管理

公式字段示例:

关联字段示例:

数据表管理

⚠️ 权限管理（重要）：

• 通过 API 创建的表格默认只对机器人可见
• 创建后需添加用户为协作者：

• 权限类型：view / edit / full_access

视图管理

视图类型: grid(表格) / kanban(看板) / gallery(画册) / gantt(甘特图)

权限管理

角色类型: owner / editor / reader

⚠️ 不存在的接口

/apps/:app_token/tables/:table_id/statistics 该接口不存在，飞书官方文档中未提供统计汇总 API。

如需统计数据（如求和、计数），建议：

1. 用 POST .../records/search 拉取全量记录后在客户端计算
2. 在多维表格中创建公式字段（如 SUM、COUNT）后通过 API 读取字段值

最佳实践

1. 批量操作优先（减少 API 调用）
2. 字段类型严格匹配（避免写入失败）
3. 日期用毫秒时间戳（Python: int(datetime.timestamp() * 1000)）
4. 关联字段实现关系型能力
5. 创建表格后立即添加用户为协作者（避免不可见）
6. 单选字段自动创建选项（直接写入选项文本即可）

测试验证

已通过实测验证的 15 种字段类型：

• 文本、进度、多选、单选、日期、复选框、电话、人员、超链接
• 邮箱、货币、评分、地理位置、单向关联、双向关联

测试表格：https://jvbmlo28x0.feishu.cn/base/YdOpb47PvalSbQsHPyXc7LrNnUh