飞书多维表格API调用前必须确认三件事：配置身份凭证（动态获取tenant_access_token）、开通多维表格权限并设置IP白名单、准确获取table_id和view_id（需开启开发者模式）。
飞书多维表格 API 调用前必须确认的三件事
不配置好身份凭证、权限和接口地址，脚本连 401 都不会报，直接返回空数据或 invalid_request。飞书开放平台要求每个调用都带 Authorization 头，且 token 有 2 小时有效期——这意味着不能硬编码 tenant_access_token 或 user_access_token，必须动态获取。
- 在「飞书开放平台」创建自建应用，开启「多维表格」权限，并在「安全设置」里配好 IP 白名单（本地调试可先关白名单）
- 用应用凭证（
app_id+app_secret）调/auth/v3/tenant_access_token/internal/换取短期tenant_access_token，这是调表格 API 的必要凭据 - 多维表格的
table_id和view_id不是 URL 里的那一长串，而是从「开发者模式」开启后，在表格右上角「… → 开发者模式」里复制的真实 ID，形如tblxxxxxxxxxxxxxx
用 requests 调用 GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records
飞书官方 SDK（feishu-sdk）封装较重、文档滞后，直接用 requests 更可控。关键不是“怎么发请求”，而是怎么处理分页、字段映射和空值。
- 必须传
user_id_type=open_id参数，否则返回的created_by等字段为空；若需真实姓名，得额外调/contact/v3/users/{open_id} - 记录默认只返回 100 条，要全量拉取就得循环读
page_token，每次请求带上page_token和page_size=500（最大允许值） - 字段值不在
fields顶层，而在fields.{field_name}下，且不同类型字段结构不同：单行文本是字符串，人员字段是[{"id": "ou_xxx", "name": "张三"}]，日期字段是 ISO 格式字符串（如"2024-05-20T08:12:33+08:00"）
用 APScheduler 实现可靠定时，避开 time.sleep() 的坑
用 while True: do(); time.sleep(3600) 看似简单，但进程挂掉就停摆，也没错误重试。APScheduler 的 BackgroundScheduler 支持内存/数据库持久化 job，适合轻量级长期运行。
- 别用
BlockingScheduler——它会阻塞主线程，没法加日志、没法热更新配置 - 给 job 加
max_instances=1，防止前一次拉取卡住（比如网络超时），下次调度又触发新实例，导致并发冲突或重复写入 - 捕获
requests.exceptions.RequestException和飞书特有的StatusCodeError（如err_code: 999999表示 token 过期），并在异常时自动刷新tenant_access_token
数据落地别直接写 CSV，优先考虑 pandas.DataFrame + to_parquet()
多维表格字段类型动态变化，CSV 很难保持 schema 一致，且无法存嵌套结构（如人员列表）。用 Parquet 不仅压缩率高、读写快，还能保留原始类型（datetime64[ns, UTC]、category），后续做分析也省事。
立即学习“Python免费学习笔记（深入）”；
- 把每条 record 的
fields展平成 dict 时，对 list 类型字段（人员、多选、附件）用json.dumps()序列化，避免 pandas 推断成object后无法向量化操作 - 用
pd.json_normalize()处理深层嵌套字段（比如附件中的file_token和name），比手写 for 循环更稳 - 文件名建议带时间戳和
table_id，例如data_tblabc123_20240520.parquet，方便按天归档和排查
token 刷新逻辑和字段类型适配是实际跑起来最常出问题的地方，尤其当表格新增了「联系人」或「地理位置」这类复合字段时，fields 结构会突变，脚本可能突然抛 KeyError。上线前务必用「开发者模式」导出一份全量 raw data JSON 做兼容性验证。
