使用 Drive API 自动上传文件
使用幂等键、配额检查、分段上传、MCP 上传工具和故障处理，构建安全的 TrekMail Drive 上传自动化。
文章详情
类型、难度、套餐及最近更新信息。
▼
文章详情
类型、难度、套餐及最近更新信息。
- 类型
- 参考资料
- 难度
- 中级
- 套餐
- Starter · Pro · Agency · + Drive Add-on
- 最近更新
- 2026年9月10日
上传自动化是 Drive API 最实用的工作流之一。报告、发票、生成的导出文件、已签名 PDF 和支持附件无需手动拖放，就能进入正确的 TrekMail Drive 文件夹。
安全模式很简单：检查存储空间，创建或选择文件夹，发起上传，传输字节，完成上传并写入有用的审计记录。
建议的权限范围
向账户 Drive 上传时，请先使用：
drive:account:readdrive:account:write
向邮箱 Drive 上传时，请使用：
drive:mailbox:readdrive:mailbox:write
除非同一工作流确实需要，否则不要授予共享和永久清除权限。如果上传任务还会创建公开链接，请添加相应的共享权限范围。
上传前检查
上传大文件之前，请调用存储摘要或空间用量 endpoint。集成应当将“超出配额”作为正常业务结果处理，而不是视为崩溃。
良好的自动化还会检查目标文件夹是否存在。如果不存在，请使用幂等键创建文件夹，避免重试时生成重复文件夹。
REST 上传流程
- 向
POST /api/v1/drive/spaces/{space}/uploads:initiate发送文件名、大小、可选文件夹 ID 和 MIME 类型。 - 将文件字节发送到返回的上传 URL 或分段上传 URL。
- 传输成功后发送
POST /api/v1/drive/uploads/{file}:complete。 - 如果传输失败，请调用
POST /api/v1/drive/uploads/{file}:abort以尽快释放预留空间。
在预留上传容量的发起请求中使用 Idempotency-Key。每个逻辑文件使用稳定的键，例如 invoice-2026-05-001-upload。不要假定每个后续上传 endpoint 都会重放幂等结果；请保存返回的文件 ID，并在重试完成或中止传输前检查其状态。
MCP 上传流程
对于代理，建议使用一个工具：
drive_file_upload(space="account", local_path="/exports/report.pdf", folder_id=42)
MCP 封装会处理上传协商、传输、完成以及出错时中止。自定义传输逻辑可以使用底层工具，但多数工作流并不需要。
命名和文件夹约定
使用可预测的名称，以便用户日后浏览 Drive：
Reports/2026/05/monthly-summary.pdfClients/Acme/contracts/acme-renewal-2026.pdfInvoices/2026/INV-2026-0042.pdf
如果代理重复上传不同版本，请加入时间戳或版本标签。不要每周上传 final.pdf 而丢失文件含义。
故障处理
请为以下情况做好准备：
| 问题 | 建议的处理方式 |
|---|---|
| 令牌缺少权限范围 | 停止操作并请求具有所缺 Drive 权限范围的令牌 |
| 超出配额 | 报告当前用量，并链接到存储或附加组件文档 |
| 上传 URL 已过期 | 刷新分段或重新开始上传 |
| 传输期间网络故障 | 中止上传预留，并使用同一个逻辑幂等键重试 |
| 找不到文件夹 | 重新列出文件夹树；仅在工作流允许时创建目标文件夹 |
上传后
如果文件用于外部交付，请创建带有有效期和下载次数上限的共享链接。如果供内部使用，则将其保留为普通 Drive 文件。无论哪种情况，都请在 AI 代理与 API → 审计日志中确认令牌和操作顺序。
相关文章
跳转到延续此工作流的邻近指南。