# 飞书多维表格 (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` 而非空数组 `[]`。 ```python # ❌ 错误: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**: ```python # ❌ 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` 字段**,即使只是改名: ```python # ❌ 只改名会报 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 一步建表**(本会话实战验证) ```python # 创建子表时直接带字段和选项,一步到位 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,字段全部就绪无需额外操作 ``` ```python # 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)都用简单字符串 创建记录时,**直接传字符串值**即可,不需要复杂的数组/对象格式: ```python # ✅ 正确:简单字符串 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} ``` ```python # ❌ 错误:用复杂数组格式(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` 复用,避免每次重新获取 ### 批量创建记录 ```python 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: ```python 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//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)— 主子任务模式 ### 创建关联字段 ```python # 单项关联(同一张表内自引用,如「父记录」) field_data = { "field_name": "父记录", "type": 18, "property": { "multiple": False, "table_id": "tblXXX" # 链接到同一张表 } } # POST /bitable/v1/apps/{app}/tables/{table}/fields ``` ⚠️ 创建关联字段时**不要**手动添加 `table_name` 属性,飞书会自动填充。 ### 写入关联值 ```python # 创建子任务时设置父记录(值是 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"` 可以搜到所有端点