使用 gws 命令行工具快速创建 Google Sheets 费用追踪表从建表、写入到权限共享全流程【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli本指南基于 Google Workspace CLIgws内置的recipe-create-expense-tracker配方讲解如何用 4 条命令在 Google Drive 中创建一张带表头与初始数据的费用追踪电子表格并与同事共享。读者将掌握gws drive files create建表、gws sheets append追加表头与数据、gws drive permissions create授权共享的完整实战链路并了解其底层 API 调用原理。前置条件gws 环境与技能加载执行本配方前需要先完成gws的安装与认证安装下载预编译二进制放入$PATH或通过npm install -g googleworkspace/cli安装详见 README.md。认证交互式环境运行gws auth loginOAuth 浏览器授权服务账号场景设置环境变量GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE指向密钥文件详见 gws-shared。配方元数据声明了两个必需技能见 SKILL.md 的 frontmattergws-sheetsGoogle Sheets 的读写能力gws-driveGoogle Drive 文件与权限管理能力。若本地缺少这些技能可运行gws generate-skills重新生成技能文件本身位于仓库 skills/gws-sheets 与 skills/gws-drive。[!NOTE] 本配方的核心命令同样以结构化步骤登记在 recipes.toml 的create-expense-tracker条目中category 为productivity涉及sheets、drive两个服务可直接被 AI Agent 读取执行。第 1 步在 Drive 中创建电子表格gws drive files create --json {name: Expense Tracker 2025, mimeType: application/vnd.google-apps.spreadsheet}该命令调用 Drive API v3 的files.create方法。关键点--json携带请求体name为文件显示名mimeType必须是application/vnd.google-apps.spreadsheet才能创建 Google Sheets 原生表格而非普通文件命令成功后响应 JSON 中的id字段即为后续步骤所需的SHEET_ID。请将其保存并替换下文所有SHEET_ID占位符。files.create是gws drive下由 Google Discovery Service 动态生成的 API 方法不是手写封装。可通过gws drive files create --help查看其参数或gws schema drive.files.create查看完整请求/响应结构参见 gws-drive。第 2 步追加表头行gws sheets append --spreadsheet SHEET_ID --range Sheet1 --values [Date, Category, Description, Amount]append是gws sheets服务内置的辅助命令helper其实现位于 helpers/sheets.rs。从源码看它把参数翻译为 Sheets API v4 的spreadsheets.values.append调用URL 参数固定携带spreadsheetId、range以及valueInputOption: USER_ENTERED表示按用户在表格中手动输入的方式解析值日期、数字会被自动识别为对应类型请求体为{values: [[...]]}每个内层数组代表一行。append参数速查表Flag必填默认值说明--spreadsheet✓—电子表格 ID--values——逗号分隔的简单字符串单行--json-values——JSON 二维数组例如[[a,b],[c,d]]用于批量多行插入--range—A1A1 记法的目标区域如Sheet2!A1用于指定工作表标签页这里--range Sheet1将目标定位到默认的 Sheet1 标签页表头四列Date / Category / Description / Amount构成费用表的基础结构。注意原文档此处使用了--values传 JSON 数组字符串内部逗号分隔符不会被append当作列分隔符截断因为parse_append_args只在未传--json-values时才走逗号切分逻辑见 sheets.rs。第 3 步追加首条费用记录gws sheets append --spreadsheet SHEET_ID --range Sheet1 --values [2025-01-15, Travel, Flight to NYC, 450.00]与上一步完全相同的调用方式追加一行真实数据日期、类别、描述、金额。得益于USER_ENTERED的输入模式2025-01-15会被识别为日期、450.00会被识别为数字后续可直接参与求和、透视等表格运算。批量录入技巧如果有多条记录要一次性写入优先使用--json-values传二维数组例如gws sheets append --spreadsheet SHEET_ID --range Sheet1 \ --json-values [[2025-01-16, Meals, Client dinner, 120.00], [2025-01-17, Office, Stationery, 45.50]]parse_append_args会优先尝试将--json-values解析为数组的数组多行若解析失败再尝试扁平数组视为单行。该行为在 sheets.rs 中实现并有对应的单元测试test_parse_append_args_json_multi_row等验证。写操作提醒append属于写命令官方技能建议执行前先与用户确认见 gws-sheets-append。第 4 步共享给管理者只读gws drive permissions create --params {fileId: SHEET_ID} --json {role: reader, type: user, emailAddress: managercompany.com}permissions.create为指定文件添加一个访问权限参见 gws-drive--params中的fileId指定目标文件--json请求体三个字段含义role: reader只读权限如需共同编辑可改为writertype: user按具体用户共享另有group、anyone等类型emailAddress被共享者的邮箱地址。共享完成后管理者即可通过该电子表格链接查看费用数据而无需额外发送附件。验证与日常维护写入完成后可用read回读校验数据gws sheets read --spreadsheet SHEET_ID --range Sheet1!A1:Dread是只读辅助命令内部调用spreadsheets.values.get绝不会修改表格参见 gws-sheets-read 及 sheets.rs 的实现。加上--format table可获得更易读的表格输出全局格式选项json默认 /table/yaml/csv与--dry-run等安全选项见 gws-shared。日常记账可反复使用第 3 步的append命令持续追加新行或将多条记录打包为--json-values一次性写入需要导出备份时可参考 backup-sheet-as-csv 将表格导出为 CSV。Shell 转义注意事项zsh 的!历史扩展区域表达式中的!如Sheet1!A1:D10会被 zsh 当作历史扩展吞掉。zsh 下应改用双引号包裹 range 值内部引号转义例如--range Sheet1!A1:D10详见 gws-shared。JSON 双引号--params与--json的值应使用单引号包裹避免 shell 解析内部双引号本配方所有命令均已按此规范书写。总结recipe-create-expense-tracker展示了gws最具代表性的工作流模式用drive files create在 Drive 中落盘文件用sheets append向表格写入表头与数据再用drive permissions create完成协作者授权。四步全部通过统一 CLI 语法gws service resource method [flags]完成无需手写任何 REST 请求其中append辅助命令由仓库源码 helpers/sheets.rs 原生实现直接映射 Sheets API 的values.append接口兼顾了易用性与底层可追溯性。读者可将本流程扩展为任意建表 → 灌数据 → 共享场景例如销售管道跟踪、活动报名统计等。【免费下载链接】cliGoogle Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.项目地址: https://gitcode.com/gh_mirrors/cli413/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
