gog sheets batch-update一次 API 请求批量更新 Google Sheets 多个范围gogcli【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog sheets batch-update是 gogcliGoogle Workspace in your terminal中专用于 Google Sheets 的批量写入命令它把多个 range 的取值打包进一次 Google Sheetsspreadsheets.values.batchUpdate请求替代每个区域一次 API 调用的低效模式。读完本文你将掌握该命令的完整调用方式、--data-json的数据格式与输入选项USER_ENTERED/RAW、响应值回传渲染参数以及命令在 gogcli 源码中的请求构造、输入解析与校验链路。命令概览gog sheets batch-update的定义为Update values in multiple ranges with one API request并注册了batch别名见 internal/cmd/sheets.go。官方用法行gog sheets (sheet) batch-update (batch) --data-jsonSTRING spreadsheetId [flags]其中spreadsheetId是位置参数表格 ID--data-json为必填参数接受 JSON 数组或file文件引用。该命令的典型使用场景当需要同一次操作刷新同一表格的多个不连续区域表头 数据块、多个 Tab 的同一列等时用一次网络往返完成全部写入减少 API 配额消耗与脚本中的循环调用。数据格式value ranges 的 JSON 数组--data-json的值是一个 JSON 数组每个元素对应一个ValueRange包含rangeA1 记法与values二维数组两个字段[ { range: Sheet1!A1:B1, values: [[Name, Status]] }, { range: Sheet1!A2:B3, values: [ [Ada, Ready], [Grace, Blocked] ] } ]从源码的校验函数 DecodeRanges 可以看到该格式的具体约束JSON 必须是对象数组且至少包含一个value range空数组会报--data-json must contain at least one value range每个元素不能为nullrange字段不能为空--data-json range %d has empty rangevalues不能为空数组range 中的转义写法\!会被统一还原为!这样在 shell 或 JSON 中都可以安全引用含!的区域名如Sheet1\!A1:B1。解析失败会返回 usage 类错误且退出码为 2这一点由测试 TestParseSheetsBatchUpdateDataRejectsInvalidPayloads 覆盖例如空文件引用报 empty file reference、非法 JSON 报 invalid JSON data。三种输入方式内联、file、stdin--data-json的取值由 resolveInlineOrFileBytes 统一解析支持三种形态形态行为内联 JSON 字符串原样作为字节内容解析file.json从指定路径读取文件内容路径支持~展开空路径报empty file reference-或-从 stdin 读取全部输入因此完整的典型调用为gog sheets batch-update $spreadsheet_id --data-json updates.json --json对于包含!的公式或区域shell 的历史扩展、引号问题把 JSON 写入文件再经file/ stdin 传入是最稳妥的做法。值解释方式--input选项--input默认USER_ENTERED决定 Sheets API 如何解释写入的字符串USER_ENTERED默认值按用户直接在 Sheets 界面输入的方式解释公式、日期、$前缀货币等都会被解析。该默认值在源码中定义为常量sheetsDefaultValueInputOption USER_ENTEREDinternal/cmd/sheets.goRAW值按字面存储不做任何解析。适合写入形如001的纯文本避免被转成数字1或需要保持原样的字符串。gog sheets batch-update $spreadsheet_id \ --input RAW \ --data-json [{range:Sheet1!A1:B1,values:[[001,plain text]]}]响应回传--include-values-in-response与渲染选项默认情况下values.batchUpdate的响应只包含各范围的更新统计updatedRange、updatedRows、updatedColumns、updatedCells。当调用方需要拿回更新后的单元格值时追加以下参数gog sheets batch-update $spreadsheet_id \ --include-values-in-response \ --response-render UNFORMATTED_VALUE \ --data-json updates.json \ --json相关参数--include-values-in-response让响应携带更新后的值映射到请求体的IncludeValuesInResponse字段--response-render响应值的渲染方式取值FORMATTED_VALUE按显示格式、UNFORMATTED_VALUE未格式化原始值、FORMULA公式文本--response-date-time-render日期/时间的渲染方式取值SERIAL_NUMBER序列号或FORMATTED_STRING格式化字符串。这三个参数只有非空时才写入请求对象见 SheetsBatchUpdateCmd.Run 中对ResponseValueRenderOption/ResponseDateTimeRenderOption的空值判断。执行流程与输出从源码实现internal/cmd/sheets.go可以还原完整的执行链路规范化表格 IDnormalizeGoogleID会剥除空白并支持直接粘贴 Drive 分享链接——当输入是 URL 时会从drive.google.com链接的 query 参数或路径中解析出 IDinternal/cmd/googleid.go解析--data-json经resolveInlineOrFileBytesDecodeRanges得到[]*sheets.ValueRange构造请求组装sheets.BatchUpdateValuesRequestData、ValueInputOption、IncludeValuesInResponse及可选渲染选项dry-run 拦截若传了-n/--dry-run打印包含op: sheets.batch-update与完整请求体spreadsheet_id、value_input_option、data等的意图描述后以 0 退出不创建 Sheets 服务、不发起任何网络请求。测试 TestSheetsBatchUpdateCmd_DryRunSkipsService 通过一个会t.Fatal的 service 工厂验证了这一行为发起请求调用svc.Spreadsheets.Values.BatchUpdate(spreadsheetID, req).Do()对应 HTTP 端点POST /sheets/v4/spreadsheets/{id}/values:batchUpdate测试 TestSheetsBatchUpdateCmd_JSON 用 httptest 服务断言了该路径输出结果JSON 模式-j/--json输出spreadsheetId、totalUpdatedRows、totalUpdatedColumns、totalUpdatedCells、totalUpdatedSheets与responses数组便于脚本解析普通模式输出一行人类可读摘要如Updated 4 cells across 2 ranges in s1。Flags 完整参考以下为命令参考页 gog-sheets-batch-update 收录的全部标志命令特有项 全局项FlagTypeDefaultHelp--data-jsonstring必填Value ranges as JSON array, or file (e.g.[{range:Sheet1!A1:B2,values:[[a,b]]}])--inputstringUSER_ENTEREDValue input option: RAW or USER_ENTERED--include-values-in-responseboolInclude updated values in the response--response-renderstringResponse value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA--response-date-time-renderstringResponse date/time render option: SERIAL_NUMBER or FORMATTED_STRING-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully-y--force--assume-yes--yesboolSkip confirmations for destructive commands-j--json--machineboolfalseOutput JSON to stdout (best for scripting)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)-v--verboseboolEnable verbose logging--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)--disable-commandsstringComma-separated list of disabled commands; dot paths allowed--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths)--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers-h--helpShow context-sensitive help--versionPrint version and exit值得注意的 Agent/CI 安全相关组合--readonly会在运行时阻断一切变更类请求batch-update属于写操作在该模式下会被阻止适合只读审计场景--no-input保证不弹交互确认失败即报错适合无终端环境--disable-commands/--enable-commands支持点号路径如sheets.batch-update可精细收窄 CLI 能力面--access-token直接携带令牌时会绕开本地存储的 refresh token约 1 小时过期部分 API 需搭配--quota-project计费。与单范围更新的分工如果只需要更新一个范围gog sheets update更直接参考 gog-sheets-update它支持--values-json的file/-输入并且带--fail-on-formula-error时会把更新后的精确范围以结构化网格读回检测到单元格级错误时以非零码退出并返回formulaErrors含单元格、错误类型、消息。对于多范围一次写完则用batch-update两者的输入解析共用resolveInlineOrFileBytes这一套机制。验证与测试该命令的行为由 internal/cmd/sheets_batch_update_test.go 完整覆盖请求正确性断言 HTTP 路径为/spreadsheets/s1/values:batchUpdatePOST请求体中ValueInputOption、IncludeValuesInResponse、ResponseValueRenderOption与传入参数一致Data含 2 个 range 且\!已还原为!输出格式JSON 模式下 stdout 可解析出spreadsheetId、totalUpdatedCells、responses等字段dry-runservice 工厂若被调用即判失败确保预演不发请求非法输入空引用与非法 JSON 均返回退出码 2。延伸阅读Sheets Batch Updates 使用指南gog sheets 命令族全部命令索引命令参考源页由gog schema --json生成make docs-commands重新生成【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
