Microsoft Excel

核心用法

Microsoft Excel技能提供对Microsoft Graph Excel API的完整访问能力，通过Maton托管OAuth网关实现安全认证。核心功能涵盖：

数据操作：读取/写入单元格范围（A1notation）、获取已用区域、批量更新数据、清除格式或内容
工作表管理：创建、重命名、删除工作表，调整工作表顺序
表格处理：将数据范围转换为Excel表格（Table），动态添加行列，管理表头与汇总行
图表集成：在工作表中添加ClusteredColumn等图表类型
文件管理：通过OneDrive路径或文件ID访问工作簿，支持上传.xlsx文件
性能优化：使用持久化会话（Session）批量执行操作，减少认证开销

典型调用模式为https://gateway.maton.ai/microsoft-excel/{native-api-path}，自动注入OAuth令牌。

显著优点

• 企业级生态整合：原生支持OneDrive/SharePoint存储，与Microsoft 365无缝协作
• 托管OAuth安全：Maton集中管理令牌生命周期，无需开发者处理OAuth流程
• 完整API覆盖：涵盖Range、Worksheet、Table、Chart、NamedItem等全部Excel REST API能力
• 灵活寻址：同时支持文件路径（root:/path/file.xlsx）和文件ID两种访问模式
• 会话机制：持久化会话支持批量原子操作，非持久会话适合只读查询

潜在局限

• 格式限制：仅支持.xlsx格式，不兼容遗留.xls文件
• URL编码要求：工作表名含特殊字符、ID中的{ }需手动编码
• 会话超时：持久会话约5分钟空闲过期，非持久约7分钟，长任务需管理续期
• Shell环境敏感：curl命令含括号时需-g禁用glob，管道环境变量可能不展开
• 依赖Maton平台：API密钥与连接管理绑定Maton服务，存在供应商锁定风险

适合人群

• 数据分析师：需要自动化Excel报表生成、数据清洗与分发
• 企业系统集成者：将Excel作为数据交换枢纽，对接ERP/CRM系统
• 财务/运营团队：批量处理预算表、统计表，自动化图表更新
• 低代码开发者：通过REST API替代VBA宏，实现跨平台Excel操作

常规风险

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

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

| **OAuth令牌泄露** | Maton平台遭入侵可能导致Microsoft账户访问权限泄露 | 定期审查连接状态，及时删除闲置连接 |

| **数据覆盖** | PATCH操作可能意外覆盖公式、格式或他人数据 | 操作前获取usedRange备份，使用`null`值选择性更新 |

| **并发冲突** | 多会话同时修改同一工作簿可能导致数据不一致 | 使用持久会话并设置`persistChanges: true`确保写入顺序 |

| **API限流** | Microsoft Graph存在调用配额限制 | 实现429状态码重试逻辑，批量操作优先使用会话模式 |

| **权限漂移** | OAuth授权后用户修改OneDrive权限可能导致API调用失败 | 连接状态监控，异常时重新授权 |

安全建议

• API密钥存储于环境变量，禁止硬编码或提交至版本控制
• 生产环境使用专用Maton连接，避免开发/测试连接混用
• 敏感数据工作簿建议配置SharePoint权限审计日志
• 定期执行DELETE清理过期会话，减少攻击面

核心功能

Microsoft Excel技能通过Maton网关提供对Microsoft Graph Excel API的完整访问能力，支持以下核心操作：

• 工作簿管理：读取/上传.xlsx文件、搜索文件、获取驱动器信息
• 工作表操作：列出、创建、重命名、删除工作表，调整位置与可见性
• 数据范围：精确读写单元格范围（A1记号法），支持公式、数值、格式和文本获取
• 表格处理：结构化数据表的CRUD操作，支持行列增删、表头管理、自动扩展
• 图表集成：在工作表中添加和配置图表（柱状图、折线图等）
• 会话优化：创建持久化会话提升批量操作性能

显著优势

1. 托管OAuth简化认证：无需自行管理Microsoft Graph OAuth流程，Maton自动处理令牌刷新
2. 原生API完整覆盖：直接暴露Microsoft Graph Excel端点，功能与官方API一致
3. 灵活访问模式：支持文件ID和文件路径两种定位方式，兼容OneDrive和SharePoint
4. 多连接管理：可同时维护多个Microsoft账号连接，通过Maton-Connection头切换
5. 零代码依赖：纯文档型技能，示例涵盖Python、JavaScript、curl，即查即用

局限与注意事项

• 格式限制：仅支持.xlsx格式，不支持遗留.xls文件
• 会话过期：持久会话约5分钟、非持久约7分钟无活动后失效，需重建
• 特殊字符编码：工作表名含特殊字符、ID中的{}需URL编码
• 环境变量依赖：必须配置MATON_API_KEY，且示例代码未内置存在性检查
• 速率限制：受Microsoft Graph API限流策略约束（429错误）

适用人群

• 数据分析师：自动化报表生成、定期数据更新、跨系统数据同步
• 财务/运营团队：预算模板批量处理、财务数据整合、动态仪表板构建
• 开发者：构建基于Excel的数据工作流、企业系统集成、ETL管道开发
• 无代码用户：通过复制示例代码快速实现Excel自动化，无需深入Graph API文档

安全风险与建议

| 风险等级 | 描述 | 缓解措施 |

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

| 低 | API Key泄露 | 使用环境变量，避免硬编码；定期轮换密钥 |

| 低 | 会话劫持 | 敏感操作使用短期会话，完成后立即关闭 |

| 中 | 数据覆盖 | 生产操作前备份文件，使用`null`跳过非目标单元格 |

| 低 | OAuth范围过度授权 | 在`ctrl.maton.ai`审查并最小化授权权限 |

该技能经安全认证（S级，95分），无可执行代码，外部API均指向可信域名（maton.ai、microsoft.com），适合生产环境使用。