Microsoft OneDrive

核心用法

OneDrive Skill 是 Maton 平台提供的 Microsoft OneDrive API 代理服务，通过托管 OAuth 简化与 Microsoft Graph 的集成。用户无需自行处理复杂的微软 OAuth 流程，仅需 Maton API Key 即可调用完整的 OneDrive 文件管理能力。

主要功能覆盖：

• 文件浏览：支持驱动器列表、根目录浏览、按 ID 或路径获取项目、特殊文件夹（文档/照片/音乐）访问
• 搜索与筛选：关键词搜索、最近文件、共享给我文件、OData 查询参数过滤
• 完整 CRUD：创建文件夹、简单上传（≤4MB）、断点续传大文件、下载（含预授权 URL）、重命名/移动/复制/删除
• 分享管理：生成匿名/组织内分享链接、邀请特定用户并设置权限

技术特性：

• 基于 Microsoft Graph v1.0 API 的完整封装
• 支持 Maton-Connection 头实现多账户切换
• 自动令牌注入，开发者仅需关注业务逻辑

显著优点

1. 零 OAuth 维护成本：Maton 托管令牌刷新与授权流程，开发者无需维护微软应用注册和令牌生命周期
2. 企业级功能覆盖：完整支持 SharePoint/OneDrive 的复杂场景，包括大文件分片上传、复制进度监控、细粒度分享控制
3. 标准 REST 接口：兼容 OData 查询语法，支持 $select、$filter、$orderby 等标准参数
4. 多语言示例完备：提供 Python、JavaScript/curl 的即用代码片段，降低接入门槛

潜在局限

• 单文件 4MB 上传限制：大文件必须通过多步骤的 createUploadSession 流程，增加开发复杂度
• 代理依赖风险：核心功能绑定 Maton 服务可用性，若 Maton 平台故障将完全中断访问
• 微软 API 速率限制：429 限流错误直接透传，需自行实现重试逻辑
• 环境变量约束：API Key 必须通过 MATON_API_KEY 环境变量注入，灵活部署受限

适合人群

• 需要快速集成云存储的自动化脚本开发者
• 构建文档管理、备份同步、协作工作流的企业内部工具团队
• 已使用 Maton 生态、希望统一 API 网关管理的组织

常规风险

• 密钥泄露风险：API Key 即身份凭证，硬编码或日志泄露可能导致账户被完全控制
• 数据误操作：删除/覆盖操作不可逆，生产环境务必确认目标资源
• 权限范围模糊：OAuth 授权后 Maton 可访问完整 OneDrive，敏感文件需额外访问控制
• 临时下载 URL 过期：@microsoft.graph.downloadUrl 有效期短，需及时消费

核心用法

该 Skill 提供 OneDrive API 的标准化接入能力，通过 Maton 代理服务（api.maton.ai）转发请求至 Microsoft Graph API。用户需先在 maton.ai 注册获取 MATON_API_KEY，完成 OAuth 授权后即可执行文件上传下载、文件夹管理、共享链接生成等操作。

关键操作流程：
1. 配置 MATON_API_KEY 环境变量
2. 创建 OneDrive 连接并授权（POST /connections）
3. 使用连接 ID 指定目标账户（Maton-Connection 头）
4. 调用标准化 REST API 管理文件

支持功能包括：驱动器查询、文件/文件夹 CRUD、大文件分片上传（>4MB）、预认证下载 URL 获取、多种类型共享链接创建（view/edit/embed）、OData 查询参数等。

显著优点

• 托管式 OAuth：无需自行处理微软 OAuth 流程，降低开发复杂度
• 多账户管理：支持多个 OneDrive 连接，通过 Header 灵活切换
• 完整功能覆盖：涵盖从简单上传到企业级共享的完整 OneDrive API 能力
• 标准接口：遵循 Microsoft Graph 规范，熟悉微软生态的用户可快速上手
• 明确安全声明：文档强制要求写入操作前获得用户确认

潜在局限

• 第三方代理依赖：所有数据流经 Maton 服务器，存在中间人攻击和隐私泄露理论风险
• 商业服务锁定：API Key 和连接管理绑定 Maton 平台，迁移成本较高
• 网络条件要求：国内访问可能受 Maton 服务可用性影响
• 速率限制透明性：微软 Graph 的 429 错误透传，但 Maton 层可能额外限制

适合人群

• 需要快速集成 OneDrive 又不想自建 OAuth 系统的开发者
• 已在 Maton 生态中使用其他云存储 Skill 的用户
• 对 Microsoft Graph API 有一定了解，希望简化认证流程的团队
• 非敏感数据场景下的自动化文件同步需求

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 第三方代理风险 | Maton 可访问用户的 OAuth Token 和文件元数据 | 审查服务商隐私政策，敏感数据考虑直连 Graph API |

| API Key 泄露 | MATON_API_KEY 泄露可导致账户被滥用 | 使用密钥管理工具，避免硬编码，定期轮换 |

| 误操作风险 | 删除/覆盖操作不可逆 | 严格执行文档要求的用户二次确认机制 |

| 服务中断风险 | Maton 服务故障影响全部功能 | 关注服务状态，关键业务保留备用方案 |