飞书多维表格 (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 |
修正后的诊断流程:
- IM API 阳性对照 — 确认 token 有效(
GET /im/v1/chats→code:0) - bitable 创建 —
POST /bitable/v1/apps→ 如果成功(code:0),说明权限 OK - bitable 获取单个 —
GET /bitable/v1/apps/:app_token→ 如果成功,再次确认权限 OK - 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": "待办"}, # 不需要!
}
注意事项
- 单选字段值必须精确匹配 option name——先 GET /fields 查看可选值
- 文本字段直接传 string——不需要
[{"type":"text","text":"..."}]格式 - 创建前先查字段列表:
GET /bitable/v1/apps/{app_token}/tables/{table_id}/fields确认字段名和类型 - 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": "主任务标题"}]}
验证流程
- POST 主任务 → 拿到
parent_id - POST 子任务,
"父记录": [parent_id]→ 子任务自动关联主任务 - 在飞书表格界面中,子任务行会显示可点击的主任务标题链接
- 始终用 IM API 做阳性对照——先确认 token 有效再诊断 bitable
- 404 错误 = 先排查权限,再排查路径
- 飞书 API 文档是 JS 渲染的 SPA,curl 抓取不到 API 路径(空结果)
- lark CLI 二进制内嵌了完整的 API 路径表,用
strings lark-cli | grep "open-apis/bitable"可以搜到所有端点