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

alwaysrun
0 阅读5分钟

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

整体架构

上传流程的架构设计：

uploader-arch.png

核心流程

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

步骤 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. 飞书云盘中已有目标文件夹（用于存放上传的报告）

配置流程概览

upload-feishu-config.png

阶段一：创建飞书应用

1.1 进入开发者后台

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

1.2 填写应用信息

字段说明
应用名称应用的显示名称
应用描述功能简介
应用图标上传图标（可选）

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

1.3 记录应用凭证

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

凭证说明特征
App ID应用唯一标识以 cli_ 开头
App Secret应用密钥点击查看

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

阶段二：配置 API 权限

2.1 进入权限管理

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

2.2 搜索并添加所需权限

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

权限名称权限标识类型用途
上传、下载文件到云空间drive:file:upload租户级上传文件到云盘
查看、评论、编辑和管理云空间中所有文件drive:file租户级完整文件访问（备选）

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

阶段三：发布应用

3.1 创建版本

  1. 进入「应用发布」→「版本管理与发布」
  2. 点击「创建版本」
  3. 填写版本信息：
字段值
版本号1.0.0
更新说明初始版本，支持云盘文件上传功能
可用范围
  1. 点击「保存」

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

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

4.1 启用机器人能力

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

4.2 添加应用为文件夹协作者

有两种方法可以授权：

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

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

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

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

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

4.3 获取文件夹 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
变量来源示例
APP_ID开发者后台 → 凭证与基础信息cli_a1b2c3d4e5f6g7h8
APP_SECRET开发者后台 → 凭证与基础信息aB1cD2eF3gH4iJ5kL6mN7oP8
FEISHU_FOLDER_TOKEN飞书云盘 URLfldcnAbCdEfGhIjKlMnO

常见问题排查

错误码描述解决方案
1061004权限不足将应用添加为文件夹协作者，权限设为可编辑
1061073未开通权限在开发者后台申请 drive:file:upload 权限
1061044文件夹不存在检查 FEISHU_FOLDER_TOKEN 是否正确
99991663应用未找到确认应用已发布且机器人已启用

★ 源码 URL：github.com/alwaysrun/E…

avatar
文章
阅读
粉丝