Python+飞书API实现多维表格批量删除与定时清理-代码聚汇网

Python+飞书API实现多维表格批量删除与定时清理

魏金华·2026-08-31·阅读 24 GEO检测（免费）

飞书多维表格PythonAPI

|难度：普通|阅读约 20 分钟

1. 项目背景与需求分析

1.1 需求场景还原

最近我在做一个数据清洗项目，需要定时从飞书多维表格中查询并删除过期记录。这个需求听起来很常见，但实际落地时发现坑不少。飞书多维表格的API文档虽然公开，但涉及查询、删除的细节处理，尤其是Python的集成方式，官方给的示例代码和实际生产环境差距不小。

我处理的场景是这样的：公司运营团队每天会往一个飞书多维表格里录入大量客户跟进记录，每条记录都有“创建时间”字段，我们需要定期清理掉超过30天且状态为“已关闭”的旧数据。一方面是为了提升表格的查询性能，另一方面也是合规要求——客户数据不能长期留存。

刚开始我打算用飞书内置的自动化流程来处理，但发现多维表格的自动化规则对删除操作支持有限，而且无法灵活控制删除条件。于是转向Python + 飞书开放API的方案，这是最直接、可控性最强的路径。

1.2 技术选型逻辑

为什么选择Python而不是其他语言？一是因为飞书官方提供了Python SDK（虽然版本更新慢，但基础功能够用），二是因为Python在处理数据清洗、批量操作这类任务上天然适合。更重要的是，我后续需要把这个删除脚本集成到定时任务中，Python的schedule库或者APScheduler都可以无缝对接。

查询和删除这两个操作，在飞书API中其实对应的是不同的接口。查询用的是“记录列表”接口，支持筛选条件；删除用的是“批量删除记录”接口，每次最多删除500条。这里有个关键点：删除前必须先查询出符合条件的记录ID，然后拿着ID去删除。所以整个流程可以拆解为：查询-获取ID列表-批量删除-验证删除结果。

1.3 权限与API基础准备

在开始写代码之前，有两件事必须先搞定。第一是飞书开放平台的App创建，第二是获取tenant_access_token。

飞书多维表格的API基于App的权限模型，你需要创建一个企业自建应用，然后申请“多维表格”相关的权限。具体来说，需要开通bitable:record:read（读取记录）和bitable:record:write（写入/删除记录）这两个权限。别小看这一步，很多人卡在权限申请上，因为飞书的应用权限审批流程比较繁琐，需要管理员手动确认。

获取token的方式是调用飞书身份验证接口，传入app_id和app_secret。这个token的有效期是2小时，所以代码里需要做缓存处理，避免每次请求都重新获取。我习惯用Python的time模块记录token的过期时间，到期前自动刷新。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 飞书多维表格API的核心机制详解

2.1 记录查询API的调用方式

飞书多维表格的查询接口是GET /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records。这个接口支持分页、筛选和排序，但新人最容易踩的坑是筛选条件的写法。

筛选条件不是你想的SQL where语句，而是飞书自己定义的一套JSON格式。比如我要筛选“创建时间大于30天前并且状态为已关闭”，需要这样构造：

json复制{
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "创建时间",
        "operator": "isLess",
        "value": "2024-01-01T00:00:00+08:00"
      },
      {
        "field_name": "状态",
        "operator": "is",
        "value": "已关闭"
      }
    ]
  }
}

看到没，时间字段的筛选必须用ISO 8601格式，而且时区要明确。我一开始没注意时区问题，导致筛选出来的记录总是对不上，折腾了半天才发现是UTC和北京时间差了8小时。

2.2 分页查询的边界处理

飞书的查询接口默认一次返回20条记录，最大可以设置到500条。但你的删除操作可能涉及成千上万条记录，所以必须处理分页。

分页参数很简单：page_size 和 page_token。第一次请求不带page_token，返回结果里会包含has_more和next_page_token。你需要循环请求直到has_more为false。

这里有个性能优化点：查询接口每次请求都有一定的延迟，如果你一次只查20条，循环次数太多会很慢。我建议直接把page_size设成500，一次性拉满，减少请求次数。但注意，如果你的筛选条件比较复杂，返回500条数据可能需要2-3秒，要做好超时处理。

2.3 记录ID的获取与格式

查询返回的每条记录都有一个record_id字段，这个ID是字符串，格式类似recxxxxx。记住，这个ID是多维表格内部的唯一标识，删除操作必须用这个ID，而不能用其他的字段值。

我遇到过一种情况：多条记录的时间戳完全相同，导致查询结果顺序不稳定，翻页时可能出现重复或遗漏。飞书这个问题的官方解释是“默认不保证排序顺序”，解决方案是在查询时显式指定排序字段，哪怕你用_id排序也好。

3. Python代码实现：查询与删除全流程

3.1 环境准备与依赖安装

先列一下我用的Python环境：Python 3.10，依赖包只有requests和json，没有用飞书官方SDK。为什么不用官方SDK？因为官方SDK的封装太厚重，而且有些接口的版本对不上，出了问题排查起来反而麻烦。直接用requests调用REST API，自己控制所有细节，出了问题一眼就能看出来。

安装命令：

bash复制pip install requests

就这一个包就够了，其余的依赖都是标准库。

3.2 获取token的核心代码

token获取是基础操作，但必须做好缓存机制。我写了一个get_token函数，使用全局变量存储token和过期时间，避免频繁请求。

python复制import requests
import time

class FeishuClient:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.token = None
        self.token_expire = 0

    def get_token(self):
        if self.token and time.time() < self.token_expire - 60:
            return self.token
        url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
        payload = {
            "app_id": self.app_id,
            "app_secret": self.app_secret
        }
        resp = requests.post(url, json=payload, timeout=10)
        data = resp.json()
        if data.get("code") != 0:
            raise Exception(f"获取token失败: {data.get('msg')}")
        self.token = data["tenant_access_token"]
        self.token_expire = time.time() + data["expire"]
        return self.token

这里有个细节：我提前60秒刷新token，避免正好在临界点请求时token过期。实际生产环境中，你可以把这个时间设得更宽松些，比如120秒。

3.3 查询待删除记录的完整实现

查询是核心步骤，代码实现时要注意异常处理和分页逻辑。

python复制def query_records(self, app_token, table_id, filter_str, page_size=500):
    headers = {
        "Authorization": f"Bearer {self.get_token()}",
        "Content-Type": "application/json"
    }
    all_records = []
    page_token = None
    while True:
        params = {
            "page_size": page_size,
            "filter": filter_str
        }
        if page_token:
            params["page_token"] = page_token
        url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records"
        resp = requests.get(url, headers=headers, params=params, timeout=15)
        data = resp.json()
        if data.get("code") != 0:
            raise Exception(f"查询记录失败: {data.get('msg')}")
        items = data.get("data", {}).get("items", [])
        all_records.extend(items)
        if not data.get("data", {}).get("has_more"):
            break
        page_token = data["data"]["next_page_token"]
    return all_records

这个函数返回的是完整记录列表，每个元素包含record_id和其他字段值。但实际删除时只需要record_id，所以你可以进一步提取ID列表。

3.4 批量删除记录的实现技巧

删除接口是POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_delete，请求体是一个JSON，包含record_ids数组。注意，这个接口一次最多只能传500个ID，如果你要删除的记录超过500条，必须分批处理。

python复制def delete_records(self, app_token, table_id, record_ids):
    headers = {
        "Authorization": f"Bearer {self.get_token()}",
        "Content-Type": "application/json"
    }
    # 分批处理，每批500条
    batch_size = 500
    total = len(record_ids)
    success_count = 0
    fail_count = 0
    for i in range(0, total, batch_size):
        batch = record_ids[i:i+batch_size]
        payload = {
            "records": batch
        }
        url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_delete"
        resp = requests.post(url, headers=headers, json=payload, timeout=30)
        data = resp.json()
        if data.get("code") == 0:
            success_count += len(batch)
            print(f"成功删除第{i//batch_size + 1}批，共{len(batch)}条")
        else:
            fail_count += len(batch)
            print(f"删除失败: {data.get('msg')}, 批次ID范围: {batch[0]} - {batch[-1]}")
    return success_count, fail_count

这里我加了一个失败计数，并且打印出失败批次的记录ID范围，方便后续手动排查。实际生产环境中，你可能需要把这些失败记录写入日志文件或者重新推送到消息队列里。

3.5 全流程串联：从查询到删除

把上面两部分组合起来，就是完整的删除流程：

python复制def clean_old_records(self, app_token, table_id, filter_str):
    records = self.query_records(app_token, table_id, filter_str)
    if not records:
        print("没有需要删除的记录")
        return
    record_ids = [r["record_id"] for r in records]
    print(f"准备删除{len(record_ids)}条记录")
    success, fail = self.delete_records(app_token, table_id, record_ids)
    print(f"删除完成: 成功{success}条, 失败{fail}条")

这个函数看起来简单，但我在实际使用中加了不少防御性代码。比如，查询出来的记录数如果超过10000条，我会先打印警告，让用户确认后再执行删除，防止误操作。

4. 踩坑实录与排错指南

4.1 筛选条件格式错误：最常见的报错

我遇到的第一个坑就是筛选条件格式不对。飞书的筛选条件JSON里，field_name必须和表格里的字段名完全一致，包括大小写和空格。如果你表格里的字段名叫“创建时间”，但代码里写成了“创建时间 ”（多了一个空格），API直接返回参数错误。

更坑的是，飞书对字段值的类型检查非常严格。比如“状态”字段如果是单选类型，value必须传选项的id，而不是选项的显示文本。你需要先通过获取字段列表接口，把每个字段的选项ID映射表拉下来。

python复制def get_field_options(self, app_token, table_id, field_name):
    # 获取字段详情，找到选项ID映射
    url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/fields"
    headers = {"Authorization": f"Bearer {self.get_token()}"}
    resp = requests.get(url, headers=headers)
    fields = resp.json().get("data", {}).get("items", [])
    for field in fields:
        if field["field_name"] == field_name:
            return field.get("property", {}).get("options", [])
    return []

这个函数返回的选项列表里，每个元素有id和text两个字段。你在构造筛选条件时，要用id而不是text。

4.2 删除操作的幂等性与重试机制

飞书删除接口的幂等性设计得不太好。如果你传入一个不存在的record_id，API会返回成功，但实际上什么都没做。这就导致一个问题：如果你在查询和删除之间，有其他用户或者程序插入了新的记录，而你的删除列表里包含了这些新记录的ID（因为查询时不带条件），那么删除操作可能会跳过一些不该删的记录，或者重复删除已删除的记录。

我的解决方案是：在查询时加上严格的时间戳限制，确保只删除特定时间范围内的记录。同时，在删除后做一个验证查询，确认记录确实被删除了。

python复制def verify_deletion(self, app_token, table_id, record_ids):
    # 重新查询这些ID是否还存在
    headers = {"Authorization": f"Bearer {self.get_token()}"}
    for rid in record_ids:
        url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/{rid}"
        resp = requests.get(url, headers=headers)
        if resp.json().get("code") == 0:
            # 记录还存在，说明删除失败
            print(f"警告: 记录{rid}未被删除")

但这个验证方案也有缺点：每次验证都要发一次请求，如果待删除的记录很多，耗时会很长。所以实际使用时，我通常只对删除失败的批次做验证，而不是全量验证。

4.3 频率限制与并发控制

飞书API对每个App有频率限制，大概是每分钟200次请求。如果你的删除任务涉及大量分批请求，很容易触发限流。触发限流后API返回HTTP 429状态码，你需要等待一段时间再重试。

我实现了一个简单的重试机制：

python复制def retry_request(self, func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt * 5
                print(f"触发限流，等待{wait_time}秒后重试")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("重试次数耗尽，操作失败")

这个指数退避策略在前几次等待时间较短，后面逐渐拉长，比较适合处理临时性的限流。但如果你需要删除海量数据，建议还是分时间段执行，比如每小时只删5000条，别一次性把额度用完。

4.4 空指针异常的根源分析

有时候程序会报“Timer执行查询是报空指针”的错误。这个错误通常出现在定时任务场景下，比如你用schedule库每隔一段时间执行一次清理任务。排查下来，最常见的原因是token过期后没有正确刷新，导致后续请求使用空值token。

还有一个原因是，多维表格的app_token或table_id可能在运行过程中被修改或删除。如果你在代码里硬编码了这些ID，但运维人员不小心把表格删了重新建，ID变了，程序就会报空指针。

我的建议是：不要硬编码ID，而是通过飞书开放API的“获取应用列表”或“获取表格列表”接口动态获取最新的ID。这样哪怕表格被重建了，程序也能自适应。

5. 生产环境部署与优化建议

5.1 定时任务集成方案

目前我的方案是用Linux的crontab来调度Python脚本，每天凌晨2点执行一次清理任务。crontab配置如下：

bash复制0 2 * * * /usr/bin/python3 /path/to/cleanup.py >> /var/log/feishu_cleanup.log 2>&1

日志输出很重要，因为一旦脚本出错，你需要知道是在哪个环节出的问题。我习惯在脚本里加详细的日志，包括每一步的耗时和返回结果。

5.2 性能优化：批量操作与并发

飞书API的批量删除接口一次最多500条，这个限制无法突破。但你可以通过并发请求来加速，比如同时发送多个删除请求。不过要注意并发数量不能太高，否则容易触发限流。

我测试过的最佳并发数是3个线程，每个线程处理一个批次。再多的话，限流概率会明显增加。

python复制from concurrent.futures import ThreadPoolExecutor

def delete_records_concurrent(self, app_token, table_id, record_ids):
    batch_size = 500
    batches = [record_ids[i:i+batch_size] for i in range(0, len(record_ids), batch_size)]
    with ThreadPoolExecutor(max_workers=3) as executor:
        futures = [executor.submit(self.delete_batch, app_token, table_id, batch) for batch in batches]
        for future in futures:
            future.result()

这个方案比串行快很多，但前提是你对API的限流阈值有足够的了解，不然容易把账号封了。

5.3 数据一致性校验

删除操作完成后，我建议做一个简单的数据一致性校验。比如，查询表格中是否还有符合删除条件的记录，如果还有，说明有一部分没删干净。这时候需要重新执行查询和删除流程，直到彻底清空。

但要注意，飞书多维表格的查询接口有缓存，刚删除的记录可能还在缓存中，要等几秒才能真正反映出来。所以校验前最好加一个time.sleep(5)。

5.4 错误处理与告警机制

生产环境里的脚本不能只是默默跑完就完事，得让它能通知到人。我写了一个简单的通知函数，当删除失败率达到一定阈值时，通过飞书机器人发送告警消息。

python复制def send_alert(self, message):
    webhook_url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
    payload = {
        "msg_type": "text",
        "content": {
            "text": message
        }
    }
    requests.post(webhook_url, json=payload)

这个告警机制帮我发现了不少问题，比如有一次表格字段结构改了，导致筛选条件直接报错，要不是告警及时，我可能要到第二天才发现。

6. 代码封装与复用拓展

6.1 将功能封装为可复用的类

以上所有功能，我都封装在一个FeishuBitable类中，这样任何项目都可以直接导入使用。类的初始化函数接受配置字典，包括app_id、app_secret、app_token和table_id。这样设计的好处是，不同项目只需要传不同的配置，不用重复写代码。

python复制class FeishuBitable:
    def __init__(self, config):
        self.app_id = config["app_id"]
        self.app_secret = config["app_secret"]
        self.app_token = config["app_token"]
        self.table_id = config["table_id"]
        self.client = FeishuClient(self.app_id, self.app_secret)
    
    def clean_by_condition(self, filter_str):
        return self.client.clean_old_records(self.app_token, self.table_id, filter_str)

6.2 支持多种筛选条件的扩展

实际业务中，筛选条件可能很复杂，比如“创建时间在30天前且状态为已关闭，或者创建时间在60天前无论状态如何”。飞书API支持嵌套的筛选条件，但嵌套层级不能超过3层。

我写了一个筛选条件构造器，支持链式调用：

python复制class FilterBuilder:
    def __init__(self):
        self.conditions = []
        self.conjunction = "and"
    
    def add_condition(self, field_name, operator, value):
        self.conditions.append({
            "field_name": field_name,
            "operator": operator,
            "value": value
        })
        return self
    
    def set_conjunction(self, conjunction):
        self.conjunction = conjunction
        return self
    
    def build(self):
        return {
            "conjunction": self.conjunction,
            "conditions": self.conditions
        }

使用方式：

python复制builder = FilterBuilder()
builder.add_condition("创建时间", "isLess", "2024-01-01T00:00:00+08:00")\
       .add_condition("状态", "is", "opt_xxxxx")\
       .set_conjunction("and")
filter_str = json.dumps(builder.build())

这个构造器虽然简单，但能覆盖大部分场景。如果需要更复杂的嵌套条件，可以再扩展。

6.3 数据库迁移场景的适配

除了删除，这个代码稍加修改也可以用于数据迁移。比如，把查询出来的记录批量插入到另一个多维表格或数据库中。只需要修改delete_records部分，改成插入逻辑即可。

飞书新增记录接口是POST /open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records/batch_create，一次最多创建500条。这个接口的请求体是records数组，每个元素包含fields字段，与查询返回的格式一致。

7. 踩过的坑最后总结几点

字段名不要瞎改：表格创建后，字段名尽量不要改，否则筛选条件全部失效。如果一定要改，记得同步更新代码里的筛选条件。
测试环境一定要有：我在生产环境翻过车，原因是测试环境一切正常，但生产环境和测试环境的多维表格结构不同。后来我强制要求所有项目必须先在测试环境跑通，再用同样的配置部署到生产。
删除操作先备份：任何时候，删除数据前都要先备份。我写了一个快速备份功能，把要删除的记录导出到CSV文件，保留24小时，确保万一误删还能恢复。
API版本升级要关注：飞书开放API偶尔会更新，字段名、接口路径可能会变。我订阅了飞书开放平台的更新日志，每次版本更新都会检查自己的代码是否需要调整。
不要过度依赖SDK：官方SDK虽然方便，但版本更新滞后，且封装得太深，出了问题很难定位。直接调用REST API虽然麻烦，但可控性高，排错效率也高。