用 SQLAlchemy 连接飞书多维表格：从概念到代码实战

飞书多维表格的底层数据结构与关系型数据库高度相似——它由“数据表（table）”、“字段（field）”和“记录（record）”构成，天然适合用 SQL 思维来操作。社区项目 pybitable 正是利用这一点，实现了 SQLAlchemy 方言，让开发者可以直接用 ORM 或 Core 方式对多维表格进行查询与读写。下面从概念、鉴权到代码，完整走通这条链路。

1. 飞书多维表格：一张“长得像数据库”的在线表格

飞书多维表格（Bitable）首先是面向业务团队的在线协同工具，但它开放的 API 资源模型与数据库设计高度对应：

• 多维表格 App（app_token） ：相当于一个“数据库实例”，是容纳数据表的容器。一个 Base 中可以包含多个数据表。
• 数据表（table_id） ：相当于一张“表”，是记录和字段的集合。pybitable 中的 __tablename__ 即对应 table_id。
• 字段（field） ：相当于“列”，飞书支持文本、数字、单选、多选、日期等二十余种字段类型。
• 记录（record） ：相当于“行”，每条记录有唯一的 record_id，在 ORM 映射中通常作为主键使用。
• 视图（view） ：数据的呈现方式（表格、看板、日历等），不影响底层存储结构。

这种模型使得多维表格可以被“伪装”成一个 SQL 数据源。pybitable 的核心工作，就是把 SQLAlchemy 生成的查询翻译成飞书多维表格的 REST API 调用，再把返回的 JSON 还原成行与列。

2. 申请飞书 Key：两条路径

连接多维表格需要 app_token 和一种鉴权凭证。鉴权有两条路径，按需选择。

路径 A：创建自建应用（app_id + app_secret）

适合需要以“应用身份”长期、稳定运行的场景，权限管理也更细粒度。

1. 登录飞书开放平台（open.feishu.cn），进入开发者后台。
2. 点击“创建企业自建应用”，填写名称与描述后创建。
3. 进入应用详情页，在“凭证与基础信息”中复制 App ID（cli_ 开头）和 App Secret。
4. 进入“权限管理”，搜索并开通与多维表格相关的权限，至少需要 查看、评论和编辑多维表格（bitable:app） 。如果涉及记录增删改，还需开通对应的记录级权限。
5. 发布应用版本，等待企业管理员审核通过后，权限才会生效。

此外，还需确保该应用是多维表格的所有者或协作者，否则即使有权限，调用仍会失败。

路径 B：使用 Personal Base Token（推荐用于快速接入）

飞书为多维表格提供了独立的鉴权体系 PersonalBaseToken，无需创建自建应用，直接在网页端获取即可。对个人开发者或原型验证来说，这条路径更轻量。

获取方式：打开目标多维表格 → 点击插件/扩展入口 → 选择“自定义插件”或“自定义扩展” → 点击 获取授权码，复制得到的 PersonalBaseToken。

同时，在同一个插件入口中也可以获取该 Base 的 app_token。使用 PersonalBaseToken 时，连接字符串中的它会被 SQLAlchemy 视为“密码”并在日志中显示为星号，因此更推荐这种写法。

3. pybitable 示例代码

pybitable 提供 SQLAlchemy 方言，支持 Core 和 ORM 两种风格。

安装

pip install pybitable[sqlalchemy]

连接字符串

两种鉴权方式的 URL 格式不同：

# 方式 A：app_id + app_secret
db_url = "bitable+pybitable://<app_id>:<app_secret>@open.feishu.cn/<app_token>"

# 方式 B：Personal Base Token（推荐，日志中显示为星号）
db_url = "bitable+pybitable://:<personal_base_token>@base-api.feishu.cn/<app_token>"

SQLAlchemy Core：直接执行 SQL

from sqlalchemy import create_engine, text

engine = create_engine(db_url, echo=False)

with engine.connect() as conn:
    result = conn.execute(
        text("select `文本` as a from tblID0QbOnjktwdC")
    )
    for row in result:
        print(row)

这里 tblID0QbOnjktwdC 是数据表的 table_id，反引号用于包裹飞书字段名（尤其是中文或含空格的字段）。

SQLAlchemy ORM：声明式映射

from sqlalchemy import Column, String, Text, text
from sqlalchemy.orm import declarative_base, sessionmaker

Base = declarative_base()

class BITable1(Base):
    __tablename__ = "tblID0QbOnjktwdC"

    record_id = Column(String(32), primary_key=True)
    文本 = Column(Text, nullable=True, server_default=text("''"))
    单选 = Column(String(32), nullable=True, server_default=text("''"))
    多选 = Column(Text, nullable=True, server_default=text("''"))

Session = sessionmaker(engine)

with Session.begin() as session:
    for item in session.query(BITable1).all():
        print(
            "record_id:", item.record_id,
            "文本:", item.文本,
            "单选:", item.单选,
            "多选:", item.多选,
        )

映射的关键点：__tablename__ 填入 table_id；record_id 作为主键；属性名与飞书字段名完全一致（包括中文）。

命令行快速验证

pybitable 还提供了 CLI，适合在不写代码的情况下快速验证连接与查询：

pip install pybitable[cli]

# Personal Base Token 方式
pybitable -h base-api.feishu.cn -p <personal_base_token> <app_token>

# app_id / app_secret 方式
pybitable -h open.feishu.cn -u <app_id> -p <app_secret> <app_token>

CLI 会自动进入一个可执行 SQL 的交互环境，可以直接用 select * from 表名 验证数据是否可读。

使用提醒

• pybitable 是社区项目，并非飞书官方出品，生产环境使用前建议评估版本稳定性与 API 兼容性。
• 飞书多维表格 API 对批量操作有单次上限（通常为 500 或 1000 条），且写操作建议对单一 Base 串行执行，避免并发写入冲突。
• 如果表格开启了高级权限，当前鉴权身份必须拥有对应数据表的读取/编辑权限，否则可能返回空结果或权限错误。

pybitable 的价值在于把多维表格还原成一个可查询的数据源，让熟悉 SQLAlchemy 的开发者不必从零封装 REST 调用。对于数据导出、轻量 ETL、内部工具对接等场景，这是一条成本较低的接入路径；若业务对稳定性和官方支持有更高要求，则可以直接使用飞书官方 OpenAPI 或 BaseOpenSDK 作为底层方案。