bitable-api-notes.md 12.7 KB

飞书多维表格 (Bitable) API 实战笔记

权限模型

多维表格 API 需要应用在飞书开放平台单独开通权限 scope。IM 权限和 bitable 权限是独立的——IM 能正常通信不代表 bitable 能通。

必要权限:

  • bitable:app — 获取表格元数据、列出子表
  • bitable:app:readonly — 只读访问记录

关键诊断信号:未开通 bitable 权限时,API 返回 404 page not found(不是 403 Forbidden),容易误判为端点不存在。

端点验证矩阵(含表/字段操作)

端点 tenant token 说明
POST /bitable/v1/apps ✅ 200 创建 含 fields 一次性建表
GET /bitable/v1/apps (列表) ❌ 404 需 user token
GET /bitable/v1/apps/:app_token ✅ 200 获取单个表格元数据
PATCH /bitable/v1/apps/:app_token ❌ 404 改名用 PUT 即可
GET /bitable/v1/apps/:app_token/tables ✅ 200 列出子表
POST /bitable/v1/apps/:app_token/tables ✅ 200 创建子表(可带 fields)
DELETE /bitable/v1/apps/:app_token/tables/:tid ✅ 200(需编辑权限) 无编辑权限时静默失败
GET /bitable/v1/apps/:app_token/tables/:tid/fields ✅ 200 列出字段
POST …/fields ✅ 200 创建 新建字段
PUT …/fields/:fid ✅ 200 更新字段(type 必填)
PATCH …/fields/:fid ❌ 404 不支持 PATCH
DELETE …/fields/:fid ✅ 200 删除字段
GET …/fields/:fid ❌ 404 单字段详情不支持

关键发现(实战验证 2026-07-10):GET /bitable/v1/apps(列表端点)对 tenant_access_token 永久返回 404,即使应用已开通 base:app:read 的应用身份权限。但 CRUD 单个表格(创建/获取/更新)的端点都能正常工作!这说明列表端点需要 user_access_token(用户身份),不是因为权限没开。

⚠️ 404 双重含义 — 必须区分!

场景 404 含义 验证方法
权限未开通 飞书拦截,路由不可达 /apps/app_dummy → 400 NOTEXIST(路由存在但被拦截)
tenant token 不支持列表 端点不支持当前 token 类型 POST /apps 创建成功 + GET /apps/:token 获取成功 → 权限 OK,但列表端点仅供 user token

修正后的诊断流程:

  1. IM API 阳性对照 — 确认 token 有效(GET /im/v1/chats → code:0)
  2. bitable 创建 — POST /bitable/v1/apps → 如果成功(code:0),说明权限 OK
  3. bitable 获取单个 — GET /bitable/v1/apps/:app_token → 如果成功,再次确认权限 OK
  4. bitable 列表 — GET /bitable/v1/apps → 如果此时仍是 404,且 (2)(3) 都成功 → 不是权限问题,是 tenant token 不支持列表端点

结论:需要列表多维表格时,必须用 user_access_token(OAuth 授权)。tenant_access_token 只支持对已获取 app_token 的单个表格进行 CRUD。

读写权限矩阵

操作 需要权限 403 含义
GET 获取元数据/表/记录 bitable:app:readonly —
PATCH 改名(app/table) bitable:app 缺少写权限
POST 新增字段/记录 bitable:app 缺少写权限
DELETE 删字段 bitable:app 缺少写权限

诊断: bitable:app:readonly 能读但不能写。写操作返回 {"code":91403,"msg":"Forbidden"} (HTTP 403)。

解决: 飞书开放平台 → 应用 → 权限管理 → 把 bitable:app:readonly 改为 bitable:app(后者包含读写)。

已知限制

空记录查询返回 items: null

飞书多维表格查询无记录时返回 {"data":{"items":null,"total":0}},items 是 JSON null 而非空数组 []。

# ❌ 错误:key 存在但值为 null → get 返回 None → len(None) 抛 TypeError
items = result.get("data", {}).get("items", [])
print(len(items))  # TypeError: object of type 'NoneType' has no len()

# ✅ 正确:用 or 运算符处理 null 情况
items = result.get("data", {}).get("items") or []

触发条件: 表格完全没有记录(total=0)时,items 为 null;有记录时 items 是正常数组。因此测试环境刚建表时一定会命中此坑。

列表端点

  • GET /open-apis/bitable/v1/apps — 对 tenant_access_token 返回 404(即使权限已开通)。创建(POST)和获取单个(GET /:app_token)都能成功,说明不是权限问题而是 tenant token 类型不支持列表端点。需要 user_access_token 才能列出表格。
  • POST /open-apis/bitable/v1/apps — tenant token 可成功创建多维表格(需 base:app:create 权限)
  • GET /open-apis/bitable/v1/apps/:app_token — tenant token 可成功获取单个表格元数据(需 base:app:read 权限)
  • PATCH /open-apis/bitable/v1/apps/:app_token — 对 tenant token 返回 404(需 base:app:update 权限,可能需 user token)

Drive API 搜索多维表格

  • GET /open-apis/drive/v1/files?file_types=bitable — 返回文件但 type 是 docx,不能用于检索多维表格文件
  • 多维表格的 file type 在 Drive API 中不是 bitable

lark CLI

  • lark base app list — 需要用户授权(OAuth),tenant_access_token 不够
  • Android/Termux 上 lark auth login 因 Go DNS 问题无法完成(见 SKILL.md 故障排除)

字段操作(实战验证 2026-07-10)

关键:PUT 而不是 PATCH

飞书多维表格字段更新不支持 PATCH,必须用 PUT:

# ❌ PATCH — 返回 404
req = urllib.request.Request(url, data=data, headers=H, method="PATCH")

# ✅ PUT — 需要带 type 字段
req = urllib.request.Request(url, data=data, headers=H, method="PUT")

PUT 必须带 type 字段,即使只是改名:

# ❌ 只改名会报 400 "type is required"
{"field_name": "New Name"}

# ✅ 正确:带上 type
{"field_name": "New Name", "type": 1}

字段类型速查

type 名称 property
1 文本 —
3 单选 {"options": [{"name": "选项1"}, ...]}
5 日期 —
17 附件 —
18 关联记录 {"multiple": false, "table_id": "tblXXX"} — 单项关联;"multiple": true 多项

完整建表流程

推荐:POST /tables 带 fields 一步建表(本会话实战验证)

# 创建子表时直接带字段和选项,一步到位
POST /bitable/v1/apps/{app_token}/tables
body = {
    "table": {
        "name": "需求表",
        "fields": [
            {"field_name": "标题", "type": 1},
            {"field_name": "类型", "type": 3, "property": {
                "options": [{"name": "Bug"}, {"name": "Feature"}]
            }},
            {"field_name": "日期", "type": 5},
        ]
    }
}
# → ✅ 200,返回 table_id,字段全部就绪无需额外操作
# 1. 创建多维表格
POST /bitable/v1/apps  body={"name": "My Table"}
# → 返回 app_token

# 2. 获取默认表(创建时自带"数据表")
GET /bitable/v1/apps/{app_token}/tables
# → 返回 table_id

# 3. 重命名字段(PUT,带 type)
PUT /bitable/v1/apps/{app_token}/tables/{table_id}/fields/{field_id}
body={"field_name": "To Do", "type": 1}

# 4. 新建字段
POST /bitable/v1/apps/{app_token}/tables/{table_id}/fields
body={"field_name": "类型", "type": 3, "property": {"options": [{"name": "Bug"}, ...]}}

# 5. 删除不需要的字段
DELETE /bitable/v1/apps/{app_token}/tables/{table_id}/fields/{field_id}

记录创建 — 字段值格式(实战验证 2026-07-24)

关键发现:单选字段(type=3)和文本字段(type=1)都用简单字符串

创建记录时,直接传字符串值即可,不需要复杂的数组/对象格式:

# ✅ 正确:简单字符串
fields = {
    "需求标题": "清理4个stale状态机异常 [主任务]",   # type=1 文本 → string
    "描述": "### 为什么做\n...",                     # type=1 文本 → string
    "状态": "待办",                                  # type=3 单选 → string (必须匹配 option name)
    "类型": "Task",                                  # type=3 单选 → string
    "优先级": "P1-高",                               # type=3 单选 → string
}
# POST /bitable/v1/apps/{app_token}/tables/{table_id}/records
# body = {"fields": fields}
# ❌ 错误:用复杂数组格式(API 返回 code=1254060)
fields = {
    "需求标题": [{"type": "text", "text": "标题内容"}],  # 不需要!
    "状态": {"text": "待办"},                            # 不需要!
}

注意事项

  1. 单选字段值必须精确匹配 option name——先 GET /fields 查看可选值
  2. 文本字段直接传 string——不需要 [{"type":"text","text":"..."}] 格式
  3. 创建前先查字段列表:GET /bitable/v1/apps/{app_token}/tables/{table_id}/fields 确认字段名和类型
  4. token 缓存:token 有效期 2 小时,写入 ~/tmp/feishu_token.txt 复用,避免每次重新获取

批量创建记录

def create_record(fields):
    body = json.dumps({"fields": fields}).encode('utf-8')
    req = urllib.request.Request(API, data=body,
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
        method='POST')
    with urllib.request.urlopen(req, timeout=15) as r:
        return json.loads(r.read())

# 循环调用即可,飞书 API 没有批量创建端点(tenant token)
for task in tasks:
    result = create_record(task['fields'])
    print(f"record_id={result.get('data',{}).get('record',{}).get('record_id','')}")

Python 访问模板

当 lark CLI 无法完成用户授权时,直接用 Python urllib + tenant_access_token:

import json, urllib.request, urllib.error

APP_ID = "cli_xxx"
APP_SECRET = "xxx"

# 1. 获取 tenant_access_token
data = json.dumps({"app_id": APP_ID, "app_secret": APP_SECRET}).encode()
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
    data=data, headers={"Content-Type":"application/json"}, method="POST")
with urllib.request.urlopen(req, timeout=15) as r:
    token = json.loads(r.read())["tenant_access_token"]

auth = {"Authorization": "Bearer " + token}

# 2. 诊断:先测 IM(确认 token 有效)
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/im/v1/chats?page_size=1", headers=auth)
with urllib.request.urlopen(req, timeout=10) as r:
    print("IM OK:", json.loads(r.read())["code"])  # 应为 0

# 3. 列表格(需 bitable:app 权限)
try:
    req = urllib.request.Request(
        "https://open.feishu.cn/open-apis/bitable/v1/apps?page_size=20",
        headers=auth)
    with urllib.request.urlopen(req, timeout=15) as r:
        apps = json.loads(r.read())
        for app in apps.get("data", {}).get("items", []):
            print(f"  {app['name']} → {app['app_token']}")
except urllib.error.HTTPError as e:
    if e.code == 404:
        print("404: 未开通 bitable:app 权限,去开放平台添加")
    else:
        print(f"Error: {e.code}")

# 4. 获取指定表格的子表
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/bitable/v1/apps/<app_token>/tables",
    headers=auth)
with urllib.request.urlopen(req, timeout=15) as r:
    tables = json.loads(r.read())
    for t in tables.get("data", {}).get("items", []):
        print(f"  {t['name']} → table_id: {t['table_id']}")

关联记录字段(type=18)— 主子任务模式

创建关联字段

# 单项关联(同一张表内自引用,如「父记录」)
field_data = {
    "field_name": "父记录",
    "type": 18,
    "property": {
        "multiple": False,
        "table_id": "tblXXX"  # 链接到同一张表
    }
}
# POST /bitable/v1/apps/{app}/tables/{table}/fields

⚠️ 创建关联字段时不要手动添加 table_name 属性,飞书会自动填充。

写入关联值

# 创建子任务时设置父记录(值是 record_id 列表)
post_record(table_id, {
    "需求标题": "[S1] 子任务",
    "父记录": ["recXXXXX"],  # 父任务的 record_id
    ...
})

# 读取时,父记录返回关联记录详情
# response: {"父记录": [{"record_id": "recXXXXX", "text": "主任务标题"}]}

验证流程

  1. POST 主任务 → 拿到 parent_id
  2. POST 子任务,"父记录": [parent_id] → 子任务自动关联主任务
  3. 在飞书表格界面中,子任务行会显示可点击的主任务标题链接
  • 始终用 IM API 做阳性对照——先确认 token 有效再诊断 bitable
  • 404 错误 = 先排查权限,再排查路径
  • 飞书 API 文档是 JS 渲染的 SPA,curl 抓取不到 API 路径(空结果)
  • lark CLI 二进制内嵌了完整的 API 路径表,用 strings lark-cli | grep "open-apis/bitable" 可以搜到所有端点