Google Sheet API

核心用法

Google Sheets API Skill 是一套面向生产环境的命令行工具，封装了 Google Sheets API 的核心能力。用户通过服务账号认证后，可对电子表格执行读取、写入、追加、清除等数据操作，支持批量读写（batchGet/batchWrite）以提升效率。格式化方面涵盖单元格样式、边框、合并/取消合并单元格及格式复制。布局控制包括行列调整、自动适配与冻结窗格。表格管理支持新建工作簿、查询信息、添加/删除/重命名工作表。高级用户可直接调用原生 spreadsheets.batchUpdate 接口执行复杂操作。

显著优点

• 管道友好：JSON 输入输出设计，易于与 CI/CD、ETL 流程集成
• 多凭证源支持：灵活的环境变量与文件路径回退机制，适配不同部署场景
• 功能覆盖全面：从基础数据操作到格式、布局、工作表管理一站式解决
• 服务账号模式：适合自动化场景，无需人工 OAuth 授权流程

潜在局限

• 不支持终端用户 OAuth：无法处理需要用户同意的交互式场景
• 服务账号权限依赖：需手动分享表格给服务账号邮箱，协作场景配置较繁琐
• 无内置重试机制：需用户自行实现 429/5xx 错误的指数退避重试
• 学习曲线：A1 表示法、2D 数组结构对非技术用户不够直观

适合人群

• 需将 Google Sheets 作为轻量级数据库或数据交换层的自动化工程师
• 构建数据管道、报表系统的后端开发者
• 熟悉 Node.js 环境、偏好 CLI 工具的技术团队

常规风险

• 凭证泄露风险：服务账号 JSON 密钥一旦泄露，可被用于访问所有授权表格
• API 配额消耗：批量操作不当易触发 Google API 速率限制
• 数据覆盖风险：write/clear 等操作不可逆，缺乏内置确认机制
• 权限扩散：过度分享表格给服务账号可能导致数据暴露

核心用法

Google Sheets API Skill 是一个面向 OpenClaw 平台的生产级命令行工具，封装了 Google Sheets v4 API 的全部核心能力。它以 JSON 为数据交换格式，支持从简单读写到复杂批量操作的全场景自动化需求。

数据操作：read / write / append 覆盖基础 CRUD，batchGet / batchWrite 实现高效批量处理，clear 用于数据清理。所有命令接受 A1 表示法（如 Sheet1!A1:C10），数据通过文件引用（@path.json）或内联 JSON 传递。

格式与布局：format / getFormat 控制单元格样式，borders / merge / unmerge / copyFormat 处理视觉呈现，resize / autoResize / freeze 调整行列与冻结窗格。

工作表管理：create / info / addSheet / deleteSheet / renameSheet 实现完整的电子生命周期管理。batch 命令暴露原始 spreadsheets.batchUpdate 接口，供高级用户执行复合操作。

显著优点

• 管道友好：纯 JSON 输入输出、非零退出码、无交互设计，完美融入 CI/CD 与数据处理流水线
• 凭证灵活：支持 6 种凭证来源（环境变量、多路径文件、默认位置），适配本地开发到云部署的多种场景
• 功能完备：超越基础读写，覆盖格式化、批量操作、工作表管理等企业级需求
• 官方 SDK 背书：基于 googleapis@140.0.0 官方库，TLS 加密传输，安全审计通过

潜在缺点与局限性

• 认证模式单一：仅支持服务账号（Service Account），不支持 OAuth 2.0 用户授权流程，无法访问用户私有文档除非显式共享
• 来源可信度限制：T3 级别社区项目（个人开发者 codedao12），非 Google 官方或知名组织维护
• batch 命令风险：原始 API 暴露可能导致意外破坏性操作（删除工作表、大规模格式覆盖），需使用者具备 Sheets API 知识
• Node.js 依赖：需要 Node 运行时环境，相比纯 Shell 方案增加部署复杂度

适合人群

• 数据工程师与 DevOps：需要将 Google Sheets 作为轻量级数据仓库或配置中心的自动化场景
• 后端开发者：构建报告生成、数据同步、审批流等集成系统
• 技术团队：已有 Google Cloud 基础设施，希望标准化 Sheets 操作流程

常规风险

凭证泄露：环境变量方式虽便利，但可能残留于 shell history、CI 日志或进程列表。建议优先使用文件存储并设置 600 权限。

权限范围过大：默认使用完整 spreadsheets 范围，只读场景应配置服务账号为只读权限以实现最小权限原则。

批量操作不可逆：batch 命令与 deleteSheet 等操作无二次确认，生产环境建议先在副本验证。

API 配额与限流：Google Sheets API 有每秒请求配额，大规模操作需实现指数退避重试。