Python实现文档自动上传至飞书云盘

在完成文章分析后，需要将生成的报告自动备份到飞书云盘，避免手动传输的繁琐。

整体架构

上传流程的架构设计：

核心流程

整个上传过程分为四个步骤：

步骤 1：初始化

• 输入：环境变量（APP_ID、APP_SECRET、FEISHU_FOLDER_TOKEN）
• 处理：FeishuUploader.__init__() 从环境变量读取凭证
• 输出：配置完成的上传器实例

步骤 2：身份认证

• 输入：APP_ID + APP_SECRET
• 处理：调用 POST /auth/v3/tenant_access_token/internal
• 输出：tenant_access_token（有效期 2 小时）

步骤 3：文件上传

• 输入：文件路径 + folder_token + tenant_access_token
• 处理：使用 MultipartEncoder 流式上传到 POST /drive/v1/files/upload_all
• 输出：成功时返回 file_token

步骤 4：结果处理

• 输入：API 响应
• 处理：检查响应码，记录成功/失败日志
• 输出：布尔结果（True/False）

关键代码实现

FeishuUploader 类

这个类封装了所有与飞书 API 的交互逻辑。

获取访问凭证

def _get_tenant_access_token(self) -> Optional[str]:
    url = f"{self.BASE_URL}/auth/v3/tenant_access_token/internal"
    payload = {"app_id": self.app_id, "app_secret": self.app_secret}
    response = requests.post(url, json=payload, timeout=10)
    # 成功时返回 tenant_access_token

逻辑说明：将 App ID 和 App Secret 发送到飞书认证接口，从响应中提取访问凭证。

文件上传

def upload_file(self, file_path: Path) -> bool:
    token = self._get_tenant_access_token()
    # 使用 MultipartEncoder 构建表单
    form = {
        'file_name': file_name,
        'parent_type': 'explorer',
        'parent_node': self.folder_token,
        'size': str(file_size),
        'file': (file_name, f)
    }
    multi_form = MultipartEncoder(form)
    response = requests.post(url, headers=headers, data=multi_form, timeout=60)

逻辑说明：

1. 验证文件存在且 folder_token 已配置
2. 获取身份认证凭证
3. 构建包含文件元数据的表单
4. 流式上传到飞书云盘 API

上传触发点

在 main.py 中，分析完成后自动触发上传：

if results and any(r.success for r in results):
    report_path = reporter.generate_summaries_report(results, grouped_urls)
    logger.info("汇总分析成功，正在上传报告...")
    uploader = FeishuUploader()
    if uploader.upload_file(report_path):
        logger.info("自动上传飞书成功。")
    else:
        logger.error("自动上传飞书失败。")

飞书平台配置详解

这是整个流程中最容易出错的环节。很多开发者代码写好了，却在权限配置上卡住。

前置条件

1. 拥有飞书账号，且具有管理员权限（用于审批应用）
2. 飞书云盘中已有目标文件夹（用于存放上传的报告）

配置流程概览

阶段一：创建飞书应用

进入开发者后台

• 打开 飞书开放平台
• 使用飞书账号登录
• 点击「创建企业自建应用」

填写应用信息

填写完成后点击「创建」。

记录应用凭证

创建成功后，进入「凭证与基础信息」页面：

重要：请妥善保管这些凭证，后续 API 认证需要使用。

阶段二：配置 API 权限

进入权限管理

1. 在应用管理页面，进入「开发配置」→「权限管理」
2. 点击「开通权限」按钮

搜索并添加所需权限

在「API 权限」标签页下，搜索并添加以下权限：

推荐：使用 drive:file:upload，遵循最小权限原则。

阶段三：发布应用

创建版本

进入「应用发布」→「版本管理与发布」

点击「创建版本」

填写版本信息：

点击「保存」

阶段四：配置文件夹访问权限

还需要配置文件夹权限，应用才能上传文件。

启用机器人能力

1. 返回「开发者后台」→ 选择你的应用
2. 进入「应用功能」→「机器人」
3. 点击「启用机器人」
4. 配置机器人信息（名称、描述、头像）
5. 发布新版本以激活机器人功能

添加应用为文件夹协作者

有两种方法可以授权：

方法 A：直接添加应用到文件夹

1. 在浏览器或客户端打开飞书云盘
2. 进入目标文件夹
3. 点击右上角「 ... 」→「更多」→「添加文档应用」
4. 搜索你的应用名称
5. 选择应用，设置权限为「可编辑」
6. 点击「确认」

前提条件：应用必须已开通至少一个云文档 API 权限并已发布。

方法 B：通过群组添加应用

1. 在飞书中创建一个新群组
2. 将应用作为「机器人」添加到群组
3. 打开目标文件夹 → 点击「分享」
4. 邀请该群组作为协作者，权限设为「可编辑」

获取文件夹 Token

1.在飞书云盘中打开目标文件夹

2.从浏览器地址栏复制 URL：https://feishu.cn/drive/folder/fldcnXXXXXXXXXXXX

3. 提取 folder_token（/folder/ 后面的部分）：

folder_token = fldcnXXXXXXXXXXXX

阶段五：配置环境变量

在项目根目录创建或更新 .env 文件：

# 飞书配置
APP_ID=cli_xxxxxxxxxxxxx
APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_FOLDER_TOKEN=fldcnXXXXXXXXXXXX

常见问题排查

以上就是Python实现文档自动上传至飞书云盘的详细内容，更多关于Python文档上传飞书云盘的资料请关注脚本之家其它相关文章！