bitable-batch-archive.md 2.76 KB

飞书多维表格批量归档/迁移

把一张或多张表中的已完成/已修复/已取消等记录迁移到新建的「归档表」,保持主表清爽。

典型场景

  • 需求表、Bug 表积累大量历史已完成记录
  • 需要定期归档并保留原字段、来源和关闭时间
  • 归档表结构与主表不完全一致,需要字段映射

前置准备

Plan Agent 实际使用的表配置在 ~/tmp/fcfg.json:

import json, os
cfg = json.load(open(os.path.expanduser("~/tmp/fcfg.json")))
APP   = cfg["a"]   # app_token
REQ   = cfg["r"]   # 需求表 table_id
BUG   = cfg["b"]   # Bug 表 table_id
TOKEN = cfg["t"]   # tenant_access_token

创建归档表

推荐用 POST /bitable/v1/apps/{app}/tables 直接带字段创建:

POST /bitable/v1/apps/{APP}/tables
body = {
    "table": {
        "name": "归档表",
        "fields": [
            {"field_name": "标题", "type": 1},
            {"field_name": "描述", "type": 1},
            {"field_name": "类型", "type": 3, "property": {"options": [...]}},
            {"field_name": "优先级", "type": 3, "property": {"options": [...]}},
            {"field_name": "状态", "type": 3, "property": {"options": [...]}},
            {"field_name": "原表名", "type": 3, "property": {"options": [{"name": "需求表"}, {"name": "Bug表"}]}},
            {"field_name": "原record_id", "type": 1},
            {"field_name": "关闭时间", "type": 5},
            {"field_name": "创建时间", "type": 5},
        ]
    }
}

返回 table_id 即可使用。

字段映射

需求表和 Bug 表的字段名可能不同。归档时需要统一映射:

归档表字段 需求表来源 Bug 表来源
标题 需求标题 Bug 标题
描述 描述 描述
类型 类型 类型 / 严重程度
优先级 优先级 优先级
状态 已完成 已修复 / 已关闭

批量查询

GET /records 无记录时 items 是 JSON null,不是 []:

items = result.get("data", {}).get("items") or []

分页循环取 page_token 直到 has_more 为 false。

批量创建

飞书 tenant token 没有批量创建记录接口,只能循环单条 POST:

  • 文本字段(type=1)直接传字符串
  • 单选字段(type=3)传字符串,必须精确匹配 option name
  • 加 retry 处理网络超时
  • 写入前检查归档表是否已有该 原record_id,避免重复

批量删除

大量删除会超过 5 分钟 foreground 超时。改用 terminal(background=True, notify_on_complete=True) 执行删除脚本。

完整示例

本会话生成的脚本:~/tmp/archive_cleanup.py。复用时可调整:

  • 筛选条件(已完成/已修复/已取消)
  • 字段映射表
  • 归档表字段
  • 重试次数和超时