飞书多维表格（Feishu Bitable API）

通过飞书 Bitable API 创建和操作多维表格（类 Airtable），支持多种字段类型、CRUD 操作、筛选查询等。

触发条件

• "写个多维表格"、"创建 bitable"
• "飞书数据库"、"feishu bitable"
• "数据写到多维表格里"

初始化

import os, lark_oapi as lark
from lark_oapi.api.bitable.v1 import *

client = lark.Client.builder() \
    .app_id(os.environ['FEISHU_APP_ID_JARVIS']) \
    .app_secret(os.environ['FEISHU_APP_SECRET_JARVIS']) \
    .domain(lark.FEISHU_DOMAIN).build()

创建 Bitable App

req = CreateAppRequest.builder() \
    .request_body(ReqApp.builder()
        .name("我的多维表格")
        .folder_token("")  # 空 = 根目录
        .build()).build()
resp = client.bitable.v1.app.create(req)
app_token = resp.data.app.app_token
url = resp.data.app.url

创建数据表（带字段定义）

fields = [
    AppTableCreateHeader.builder().field_name("名称").type(1).build(),      # 文本
    AppTableCreateHeader.builder().field_name("状态").type(3).build(),      # 单选
    AppTableCreateHeader.builder().field_name("标签").type(4).build(),      # 多选
    AppTableCreateHeader.builder().field_name("日期").type(5).build(),      # 日期
    AppTableCreateHeader.builder().field_name("数值").type(2).build(),      # 数字
    AppTableCreateHeader.builder().field_name("链接").type(15).build(),     # 超链接
    AppTableCreateHeader.builder().field_name("完成").type(7).build(),      # 复选框
]
req = CreateAppTableRequest.builder() \
    .app_token(app_token) \
    .request_body(CreateAppTableRequestBody.builder()
        .table(ReqTable.builder()
            .name("任务列表")
            .default_view_name("全部")
            .fields(fields).build())
        .build()).build()
resp = client.bitable.v1.app_table.create(req)
table_id = resp.data.table_id

字段类型速查

注意: 评分字段 (type=22) API 写入可能报 WrongRequestBody，建议用数字字段替代。

添加记录

单条

record = AppTableRecord.builder().fields({
    "名称": "部署推理服务",
    "状态": "进行中",
    "标签": ["GPU", "推理"],
    "日期": int(time.time() * 1000),
    "数值": 75,
    "链接": {"text": "文档", "link": "https://example.com"},
    "完成": False,
}).build()
req = CreateAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id) \
    .request_body(record).build()
resp = client.bitable.v1.app_table_record.create(req)
record_id = resp.data.record.record_id

批量

records = [AppTableRecord.builder().fields(r).build() for r in records_data]
req = BatchCreateAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id) \
    .request_body(BatchCreateAppTableRecordRequestBody.builder()
        .records(records).build()).build()
resp = client.bitable.v1.app_table_record.batch_create(req)

查询记录

列出所有

req = ListAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id) \
    .page_size(100).build()
resp = client.bitable.v1.app_table_record.list(req)
for item in resp.data.items:
    print(item.record_id, item.fields)

条件筛选

req = ListAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id) \
    .filter('CurrentValue.[状态] = "进行中"') \
    .build()

筛选语法

CurrentValue.[字段名] = "值"              # 等于
CurrentValue.[字段名] != "值"             # 不等于
CurrentValue.[数值字段] > 50              # 大于
CurrentValue.[字段名].contains("关键词")   # 包含
AND(条件1, 条件2)                         # 且
OR(条件1, 条件2)                          # 或

更新记录

req = UpdateAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id).record_id(record_id) \
    .request_body(AppTableRecord.builder()
        .fields({"状态": "已完成", "完成": True}).build()).build()
resp = client.bitable.v1.app_table_record.update(req)

删除记录

req = DeleteAppTableRecordRequest.builder() \
    .app_token(app_token).table_id(table_id).record_id(record_id).build()
client.bitable.v1.app_table_record.delete(req)

管理数据表

列出所有表

req = ListAppTableRequest.builder().app_token(app_token).build()
resp = client.bitable.v1.app_table.list(req)
for t in resp.data.items:
    print(f"{t.table_id}: {t.name}")

删除表

req = DeleteAppTableRequest.builder() \
    .app_token(app_token).table_id(table_id).build()
client.bitable.v1.app_table.delete(req)

实际应用场景

Bot Inbox 通信

# dispatch.py 用 Bitable 做 bot 间消息队列
record = AppTableRecord.builder().fields({
    "task_id": f"dispatch-{timestamp}",
    "from": "jarvis",
    "instruction": "hostname",
    "status": "pending",
}).build()

项目管理看板

# 创建带状态流转的数据表
fields = [
    AppTableCreateHeader.builder().field_name("任务").type(1).build(),
    AppTableCreateHeader.builder().field_name("状态").type(3).build(),  # 待办/进行中/已完成
    AppTableCreateHeader.builder().field_name("负责人").type(11).build(),
    AppTableCreateHeader.builder().field_name("截止日期").type(5).build(),
    AppTableCreateHeader.builder().field_name("优先级").type(3).build(),  # P0/P1/P2
]

注意事项

• App Token vs Table ID: app_token 标识整个多维表格应用，table_id 标识其中一张数据表
• 日期格式: Unix 毫秒时间戳（int(time.time() * 1000)），不是秒
• 单选/多选自动创建: 写入未定义的选项值时，Bitable 会自动创建该选项
• 分页: list 默认返回 20 条，最多 500 条。用 page_token 翻页
• Rate limit: 约 100 次/分钟
• 权限: App 需要 bitable:app 权限
• URL 格式: https://xxx.feishu.cn/base/{app_token}

完整工作流程

1. 创建 App → CreateAppRequest → 拿到 app_token
2. 创建数据表 → CreateAppTableRequest → 定义字段和类型
3. 写入数据 → CreateAppTableRecordRequest / BatchCreate
4. 查询/筛选 → ListAppTableRecordRequest + filter
5. 更新/删除 → UpdateAppTableRecordRequest / DeleteAppTableRecordRequest
6. 返回链接 → https://xxx.feishu.cn/base/{app_token}