核心用法
OneDrive Skill 是 Maton 平台提供的托管式 API 网关，通过代理层封装 Microsoft Graph API，让用户无需直接处理复杂的 OAuth 2.0 流程即可操作 OneDrive 文件。核心工作流分为三步：
1. 连接管理：在 ctrl.maton.ai 创建 OAuth 连接，获取 connection_id 完成授权
2. API 调用：通过 gateway.maton.ai/one-drive/v1.0/ 代理端点执行操作，仅需携带 MATON_API_KEY
3. 多连接支持：支持多账户场景，通过 Maton-Connection 头部指定连接
功能覆盖完整的文件生命周期管理：
- 文件操作：上传（支持 4MB 以下直传及大文件分片上传）、下载（获取预签名 URL）、重命名、移动、复制、删除
- 文件夹管理：创建、列举、路径寻址（
:/path/to/folder:语法） - 高级功能：最近文件、共享文件、全文搜索（
$search）、OData 查询参数（$select,$filter,$orderby） - 权限共享：生成匿名/组织内共享链接、向特定用户发送邀请
显著优点
- 零 OAuth 维护成本：Maton 托管令牌刷新，避免开发者自行实现 Microsoft 身份平台的令牌生命周期管理
- 完整 Graph API 能力：非简化版 SDK，支持所有 DriveItem 操作，包括大文件分片上传等进阶场景
- 多语言友好：提供 JavaScript、Python、cURL 等完整示例，降低接入门槛
- 企业级特性：支持多连接切换、配额查询（
quota字段）、组织内共享等 OneDrive for Business 场景
潜在缺点与局限性
- 双重依赖风险：稳定性同时受制于 Maton 网关与 Microsoft Graph，任一方服务波动都会影响可用性
- 数据隐私考量：文件操作流量经过 Maton 中转，敏感场景需评估第三方网关的信任边界
- 上传大小限制：简单上传 4MB 上限需开发者自行实现分片逻辑，虽文档完整但增加复杂度
- 错误信息透传：Microsoft Graph 的原生错误码（如
itemNotFound）直接返回，调试体验取决于对 Graph API 的熟悉度 - 连接管理摩擦：OAuth 授权需人工浏览器跳转，难以完全无人化部署
适合人群
- 需要快速集成 OneDrive 且不愿维护 OAuth 的独立开发者
- 构建跨云存储自动化工作流（如定期备份、文件同步）的 DevOps 工程师
- 开发文档协作、网盘管理类应用的后端团队
- 已使用 Maton 生态、希望统一 API 密钥管理的多服务架构
常规风险
| 风险类型 | 说明 |
|---------|------|
| **密钥泄露** | `MATON_API_KEY` 泄露将导致账户级访问权限暴露，需严格环境变量隔离 |
| **共享链接泄露** | `anonymous` 范围的共享链接一旦外泄，文件可被无限制访问 |
| **意外数据操作** | `replace` 冲突行为或误删操作可能造成不可逆数据丢失，建议生产环境启用 `rename` 策略 |
| **速率限制** | Microsoft Graph 对高频调用有 429 限制，大流量场景需实现指数退避 |
| **依赖服务终止** | Maton 作为第三方平台，存在服务变更或终止的长期商业风险 |