one-drive-automation

通过 Rube MCP 自动化 OneDrive

通过 Composio 的 OneDrive 工具包自动执行 OneDrive 操作，包括文件上传/下载、搜索、文件夹管理、共享链接、权限管理和浏览云端硬盘。

工具包文档：composio.dev/toolkits/one_drive

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 OneDrive 连接，并使用工具包 one_drive
• 始终先调用 RUBE_SEARCH_TOOLS，以获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 是否可用
2. 使用工具包 one_drive 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请访问返回的授权链接，完成 Microsoft OAuth
4. 确认连接状态显示为 ACTIVE，然后再运行任何工作流

核心工作流

1. 搜索和浏览文件

适用场景：用户想要查找文件或浏览 OneDrive 中的文件夹内容

工具调用顺序：

1. ONE_DRIVE_GET_DRIVE - 验证云端硬盘访问权限并获取云端硬盘详情 [前置步骤]
2. ONE_DRIVE_SEARCH_ITEMS - 按关键字搜索文件名、元数据和内容 [必需]
3. ONE_DRIVE_ONEDRIVE_LIST_ITEMS - 列出云端硬盘根目录中的所有项目 [可选]
4. ONE_DRIVE_GET_ITEM - 获取特定项目的详细元数据，并展开子项 [可选]
5. ONE_DRIVE_ONEDRIVE_FIND_FILE - 在文件夹中按准确名称查找特定文件 [可选]
6. ONE_DRIVE_ONEDRIVE_FIND_FOLDER - 按名称查找特定文件夹 [可选]
7. ONE_DRIVE_LIST_DRIVES - 列出所有可访问的云端硬盘 [可选]

关键参数：

• q：搜索查询（仅限普通关键字，不支持 KQL 语法）
• search_scope："root"（文件夹层级）或 "drive"（包含共享项目）
• top：每页最多返回的项目数（默认值为 200）
• skip_token：来自 @odata.nextLink 的分页令牌
• select：以逗号分隔的要返回的字段（例如，"id,name,webUrl,size"）
• orderby：排序顺序（例如，"name asc"、"name desc"）
• item_id：用于 GET_ITEM 的项目 ID
• expand_relations：用于 GET_ITEM 的数组，例如 ["children"] 或 ["thumbnails"]
• user_id："me"（默认值）或特定用户 ID/电子邮件

注意事项：

• ONE_DRIVE_SEARCH_ITEMS 不支持 KQL 运算符（folder:、file:、filetype:、path:）；这些内容会被视为普通文本
• 不支持通配符（*、?），且会自动移除；请改用文件扩展名关键字（例如，使用 "pdf"，而非 "*.pdf"）
• ONE_DRIVE_ONEDRIVE_LIST_ITEMS 仅返回根目录内容；如需查看更深层级，请使用带有 expand_relations: ["children"] 的递归 ONE_DRIVE_GET_ITEM
• 大型文件夹会进行分页；请始终跟进 skip_token / @odata.nextLink，直到没有更多结果
• 由于 Microsoft Graph API 的限制，某些云端硬盘 ID 格式可能会返回“ObjectHandle is Invalid”错误

2. 上传和下载文件

适用场景：用户想要将文件上传到 OneDrive，或从中下载文件

工具调用顺序：

1. ONE_DRIVE_ONEDRIVE_FIND_FOLDER - 定位目标文件夹［前置条件］
2. ONE_DRIVE_ONEDRIVE_UPLOAD_FILE - 将文件上传到指定文件夹［上传必需］
3. ONE_DRIVE_DOWNLOAD_FILE - 按项目 ID 下载文件［下载必需］
4. ONE_DRIVE_GET_ITEM - 下载前获取文件详情［可选］

关键参数：

• file：用于上传的 FileUploadable 对象，包含 s3key、mimetype 和 name
• folder：上传的目标路径（例如 "/Documents/Reports"）或文件夹 ID
• item_id：用于下载的文件唯一标识符
• file_name：下载时使用的目标文件名，需包含扩展名
• drive_id：特定驱动器 ID（适用于 SharePoint 或 OneDrive for Business）
• user_id："me"（默认值）或特定用户标识符

注意事项：

• 发生冲突时，上传操作会自动重命名文件（默认没有覆盖选项）
• 大文件会通过分块自动处理
• 同时提供 drive_id 和 user_id 时，drive_id 优先
• 项目 ID 因平台而异：OneDrive for Business 使用 01... 前缀，OneDrive Personal 使用 HASH!NUMBER 格式
• 项目 ID 区分大小写；请使用 API 返回的原始值

3. 共享文件和管理权限

适用场景：用户想要共享文件／文件夹，或管理访问权限

工具调用顺序：

1. ONE_DRIVE_ONEDRIVE_FIND_FILE 或 ONE_DRIVE_ONEDRIVE_FIND_FOLDER - 定位项目［前置条件］
2. ONE_DRIVE_GET_ITEM_PERMISSIONS - 检查当前权限［前置条件］
3. ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM - 授予特定用户访问权限［必需］
4. ONE_DRIVE_CREATE_LINK - 创建可共享链接［可选］
5. ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA - 更新项目元数据［可选］

关键参数：

• item_id：要共享的文件或文件夹
• recipients：包含 email 或 object_id 的对象数组
• roles：包含 "read" 或 "write" 的数组
• send_invitation：true 表示发送通知邮件，false 表示静默授予权限
• require_sign_in：true 表示访问时需要进行身份验证
• message：邀请附带的自定义消息（最多 2000 个字符）
• expiration_date_time：权限到期日期，采用 ISO 8601 格式
• retain_inherited_permissions：true（默认值）表示保留现有继承权限

注意事项：

• 在 INVITE_USER_TO_DRIVE_ITEM 中使用错误的 item_id 会更改非目标项目的权限；请务必先核实
• 写入权限或更高级别的权限影响较大；授予前请征得用户明确确认
• GET_ITEM_PERMISSIONS 会返回继承权限和所有者条目；不要假设响应只反映最近的更改
• 无法通过 ONE_DRIVE_GET_ITEM 展开 permissions；请使用单独的权限端点
• require_sign_in 和 send_invitation 中至少有一个必须为 true

4. 管理文件夹（创建、移动、删除、复制）

使用场景：用户想要创建、移动、重命名、删除或复制文件和文件夹

工具调用顺序：

1. ONE_DRIVE_ONEDRIVE_FIND_FOLDER - 查找源文件夹和目标文件夹［前置条件］
2. ONE_DRIVE_ONEDRIVE_CREATE_FOLDER - 创建新文件夹［创建时必需］
3. ONE_DRIVE_MOVE_ITEM - 将文件或文件夹移动到新位置［移动时必需］
4. ONE_DRIVE_COPY_ITEM - 复制文件或文件夹（异步操作）［复制时必需］
5. ONE_DRIVE_DELETE_ITEM - 将项目移至回收站［删除时必需］
6. ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA - 重命名或更新项目属性［可选］

关键参数：

• name：创建时的文件夹名称，或重命名／复制时的新名称
• parent_folder：创建时使用的路径（例如，"/Documents/Reports"）或文件夹 ID
• itemId：要移动的项目
• parentReference：用于移动操作的对象，包含目标文件夹 ID id：{"id": "folder_id"}
• item_id：要复制或删除的项目
• parent_reference：用于复制目标位置的对象，包含 id 和可选的 driveId
• @microsoft.graph.conflictBehavior：复制时使用 "fail"、"replace" 或 "rename"
• if_match：删除时用于乐观并发控制的 ETag

注意事项：

• ONE_DRIVE_MOVE_ITEM 不支持跨驱动器移动；跨驱动器传输请使用 ONE_DRIVE_COPY_ITEM
• 移动操作中的 parentReference 需要文件夹 ID（而非文件夹名称）；请先使用 ONEDRIVE_FIND_FOLDER 解析
• ONE_DRIVE_COPY_ITEM 是异步操作；响应会提供用于监控进度的 URL
• ONE_DRIVE_DELETE_ITEM 会将项目移至回收站，而非永久删除
• 创建文件夹时发生名称冲突会自动重命名（例如，"New Folder" 会变为 "New Folder 1"）
• 使用 ONE_DRIVE_COPY_ITEM 时，必须提供 name、parent_reference 或两者

5. 跟踪更改和驱动器信息

使用场景：用户想要监控更改或获取驱动器／配额信息

工具调用顺序：

1. ONE_DRIVE_GET_DRIVE - 获取驱动器属性和元数据［必需］
2. ONE_DRIVE_GET_QUOTA - 查看存储配额（总量、已用、剩余）［可选］
3. ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA - 跟踪 SharePoint 站点驱动器中的更改［可选］
4. ONE_DRIVE_GET_ITEM_VERSIONS - 获取文件的版本历史记录［可选］

关键参数：

• drive_id：驱动器标识符（个人驱动器可使用 "me"）
• site_id：用于增量跟踪的 SharePoint 站点标识符
• token：增量令牌（"latest" 表示当前状态，URL 表示下一页，或使用时间戳）
• item_id：版本历史记录对应的文件 ID

注意事项：

• 只能通过 ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA 对 SharePoint 站点驱动器执行增量查询
• 令牌 "latest" 会返回当前增量令牌，但不包含项目（可用作起始点）
• 深层或大型驱动器可能需要数分钟才能遍历完成；请使用批处理和恢复逻辑

常见模式

ID 解析

• 用户：对已通过身份验证的用户使用 "me"，或使用特定用户的电子邮件／GUID
• 通过查找获取项目 ID：使用 ONE_DRIVE_ONEDRIVE_FIND_FILE 或 ONE_DRIVE_ONEDRIVE_FIND_FOLDER 获取项目 ID
• 通过搜索获取项目 ID：从 ONE_DRIVE_SEARCH_ITEMS 结果中提取
• 驱动器 ID：使用 ONE_DRIVE_LIST_DRIVES 或 ONE_DRIVE_GET_DRIVE 查找驱动器
• 将文件夹路径解析为 ID：使用路径调用 ONE_DRIVE_ONEDRIVE_FIND_FOLDER，然后从响应中提取 ID

ID 格式因平台而异：

• OneDrive 商业版／SharePoint：01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK
• OneDrive 个人版：D4648F06C91D9D3D!54927

分页

OneDrive 使用基于令牌的分页：

• 持续跟进 @odata.nextLink 或 skip_token，直到没有更多页面
• 使用 top 设置页面大小（因端点而异）
• ONE_DRIVE_ONEDRIVE_LIST_ITEMS 会在内部自动处理分页
• 过于频繁的并行请求可能触发 HTTP 429；请遵循 Retry-After 标头

路径与 ID

大多数 OneDrive 工具接受路径或 ID：

• 路径：以 / 开头（例如，"/Documents/Reports"）
• ID：使用 API 响应中返回的唯一项目标识符
• 权限的项目路径：使用 :/path/to/item:/ 格式

已知注意事项

ID 格式

• 项目 ID 区分大小写，且因平台而异
• 切勿将 Web URL、共享链接或手动构造的标识符用作项目 ID
• 始终按 Microsoft Graph API 返回的原样使用 ID

速率限制

• 激进地并行调用 ONE_DRIVE_GET_ITEM 可能触发 HTTP 429 Too Many Requests
• 遵循 Retry-After 标头并实施限流
• 深度遍历云端硬盘时应分批处理，并在批次之间加入延迟

搜索限制

• 不支持 KQL；仅使用普通关键词
• 不支持通配符；请使用扩展名关键词（例如，使用 "pdf"，而不是 "*.pdf"）
• 搜索不支持按路径筛选；请改用文件夹列表
• 仅包含通配符的查询 q='*' 会返回 HTTP 400 invalidRequest

参数注意事项

• 同时提供 drive_id 和 user_id 时，drive_id 优先
• 无法通过 GET_ITEM 展开 permissions；请使用专用权限端点
• 移动操作要求在 parentReference 中使用文件夹 ID，而不是文件夹名称
• 复制操作为异步操作；响应中会提供监控 URL

快速参考

任务	工具标识	关键参数
搜索文件	ONE_DRIVE_SEARCH_ITEMS	q、search_scope、top
列出根目录项目	ONE_DRIVE_ONEDRIVE_LIST_ITEMS	user_id、select、top
获取项目详情	ONE_DRIVE_GET_ITEM	item_id、expand_relations
按名称查找文件	ONE_DRIVE_ONEDRIVE_FIND_FILE	name、folder
按名称查找文件夹	ONE_DRIVE_ONEDRIVE_FIND_FOLDER	name、folder
上传文件	ONE_DRIVE_ONEDRIVE_UPLOAD_FILE	file、folder
下载文件	ONE_DRIVE_DOWNLOAD_FILE	item_id、file_name
创建文件夹	ONE_DRIVE_ONEDRIVE_CREATE_FOLDER	name、parent_folder
移动项目	ONE_DRIVE_MOVE_ITEM	itemId、parentReference
复制项目	ONE_DRIVE_COPY_ITEM	item_id、parent_reference、name
删除项目	ONE_DRIVE_DELETE_ITEM	item_id
与用户共享	ONE_DRIVE_INVITE_USER_TO_DRIVE_ITEM	item_id、recipients、roles
创建共享链接	ONE_DRIVE_CREATE_LINK	item_id、链接类型
获取权限	ONE_DRIVE_GET_ITEM_PERMISSIONS	item_id
更新元数据	ONE_DRIVE_UPDATE_DRIVE_ITEM_METADATA	item_id、字段
获取云端硬盘信息	ONE_DRIVE_GET_DRIVE	drive_id
列出云端硬盘	ONE_DRIVE_LIST_DRIVES	用户／组／站点范围
获取配额	ONE_DRIVE_GET_QUOTA	（无）
跟踪更改	ONE_DRIVE_LIST_SITE_DRIVE_ITEMS_DELTA	site_id、token
版本历史记录	ONE_DRIVE_GET_ITEM_VERSIONS	item_id

---

由 Composio 提供支持