gogcligog batch begin详解创建持久化 Google Docs 请求批次【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog batch begin是 gogcliGoogle Workspace in your terminal中批量文档编辑流程的起点命令它在本机创建一个“持久化请求批次”persisted request batch随后你可以陆续把多条 Docs 编辑操作追加进该批次最后以一次 revision-locked 的documents.batchUpdate原子提交。读完本文你将掌握gog batch begin的完整用法、全部参数语义、底层实现原理以及与batch end、--batch队列机制配合的实战工作流。一、gog batch子命令全景begin 在整个流程中的位置gog batch是一组围绕 Google Docs 批量编辑的命令族共 6 个子命令begin是整个生命周期中的第一步子命令别名功能gog batch begin—创建一个持久化请求批次本文主题gog batch listls列出已持久化的请求批次gog batch show—查看某个请求批次的内容gog batch endsubmit提交并删除请求批次gog batch abortrm, delete不提交直接删除请求批次gog batch prune—删除过期的请求批次默认--older-than 72h这些命令在 internal/cmd/batch.go 中统一注册结构清晰type BatchCmd struct { Begin BatchBeginCmd cmd: help:Begin a persisted request batch List BatchListCmd cmd: aliases:ls ... Show BatchShowCmd cmd: ... End BatchEndCmd cmd: aliases:submit ... Abort BatchAbortCmd cmd: aliases:rm,delete ... Prune BatchPruneCmd cmd: ... }批次的典型生命周期为begin创建 → 多个 Docs 命令通过--batch id追加请求 →show检查 →end原子提交若中途放弃则abort。更完整的流程说明见 docs/docs-batch.md。二、基本用法与核心参数gog batch begin的命令签名如下gog batch begin --docSTRING [flags]其中--doc是必填参数用来指定本次批次将要操作的目标 Google Doc。另有--name与--service两个批次自身的专属参数参数类型默认值说明--docstring—Google Doc ID必填--namestring—可选的批次标签batch label--servicestringdocsGoogle API 服务名当前枚举仅支持docs对应源码定义在 internal/cmd/batch.gotype BatchBeginCmd struct { Service string name:service help:Google API service enum:docs default:docs DocID string name:doc required: help:Google Doc ID Name string name:name help:Optional batch label }一个最小可用的创建命令gog batch begin --doc1AbC...xyz带标签与账户的完整形式推荐在脚本中显式指定账户BATCH_ID$(gog --account youexample.com batch begin --service docs --doc docId --name weekly update) echo $BATCH_ID三、完整 Flags 参考继承自 schemagog batch begin继承并支持以下全部 flags表格来自gog schema --json自动生成的官方文档对应 docs/commands/gog-batch-begin.mdFlag类型默认值帮助--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时后过期-a--account--acctstring认证的 Google API 命令使用的账户 email、别名或auto--clientstringOAuth client 名称选择存储的凭据与 token 桶--colorstringauto颜色输出auto\|always\|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径--docstringGoogle Doc ID必填-n--dry-run--dryrun--noop--previewbool不做任何更改打印预期动作并以成功状态退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI--enable-commands-exactstring逗号分隔的精确启用命令列表支持点路径且父命令不会启用子命令-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全-h--helpkong.helpFlag显示上下文相关的帮助信息--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--namestring可选的批次标签--no-input--non-interactive--noninteractivebool永不提示直接失败适合 CI-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的文本TSV无颜色--quota-projectstring为 API 用量计费的 Google Cloud 项目作为X-Goog-User-Project发送某些 API 配合--access-token或 ADC 时需要--readonlyboolfalse运行时阻止变更类 API 请求auth add也会请求只读 OAuth scope--results-onlyboolJSON 模式下仅输出主要结果丢弃如nextPageToken之类的信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径--servicestringdocsGoogle API 服务-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/raw 输出中将拉取的文本字段包装进外部不可信内容标记其中--doc为命令必填参数required:其他 flags 均来自根级共享配置。四、输出约定为什么文本模式只打印 UUIDgog batch begin的输出与输出模式outfmt密切相关文本 / plain / TSV 模式只向 stdout 打印一行批次 UUID例如0192f2b1-...因此用命令替换捕获批次 ID 时结果稳定不会混入其他字符JSON 模式--json/--machine输出完整的批次State结构见下一节便于脚本解析。对应实现位于 internal/cmd/batch.goif outfmt.IsJSON(ctx) { return outfmt.WriteJSON(ctx, stdoutWriter(ctx), state) } ui.FromContext(ctx).Out().Println(state.BatchID)这也是官方推荐BATCH_ID$(gog batch begin ...)这种命令替换写法的原因文本模式输出纯净、无前缀无后缀。五、源码级原理begin 到底做了什么gog batch begin的核心执行逻辑在BatchBeginCmd.Runinternal/cmd/batch.go共分五步校验--docstrings.TrimSpace后若为空直接返回empty --doc用法错误干跑支持若带有--dry-run等标志调用dryRunExit(ctx, flags, batch.begin, ...)只输出预期动作service、doc_id、name而不创建任何批次并以成功状态退出账户与客户端解析requireAccount(flags)确定账户resolveClientForEmail解析 OAuth client——被选中的账户与 client 会被记录进批次身份打开批次仓库newDocsBatchStore(ctx)基于状态目录的batches/子目录创建 docsbatch.Repository必要时创建目录并持有跨进程互斥锁创建批次状态并落盘store.Create(...)生成批次并写入磁盘。批次状态State结构批次在本地以 JSON 文件持久化核心字段定义在 internal/docsbatch/repository.gotype State struct { BatchID string json:batch_id Name string json:name,omitempty Service string json:service DocumentID string json:doc_id Account string json:account Client string json:client CreatedAt time.Time json:created_at UpdatedAt time.Time json:updated_at RequiredRevisionID string json:required_revision_id,omitempty Requests []RequestEntry json:requests }值得注意的两点begin阶段不会读取文档也不会固定 revisionCreateinternal/docsbatch/repository.go只记录账户、client、目标文档与时间戳Requests初始为空。首次排队的变更操作才会解析位置并记录文档 revision因为那时才开始解析请求位置批次 ID 使用 UUID v7 生成uuid.NewV7()见 internal/docsbatch/repository.go且写入前会再次ValidateID校验读取时也会校验“文件中存储的 batch ID 必须与文件名一致”ErrStoredIDMismatch防止状态目录被篡改。落盘与权限批次文件存放在状态目录的batches/子目录下路径由commandLayout解析见 internal/cmd/docs_batch_store.go。仓库层保证batches/目录权限为0700每个批次 JSON 文件与锁文件权限为0600writeUnlocked中显式传入0o600见 internal/docsbatch/repository.go所有写操作通过目录内.lock文件的跨进程互斥锁串行化默认锁超时 5 秒defaultLockTimeout。由于批次中的请求可能包含文档文本、链接、email 等敏感内容官方文档明确提示请把状态目录当作敏感数据目录对待。六、与后续命令的完整协作流程begin单独使用没有意义它构建的批次要配合--batch id队列机制与batch end提交形成完整闭环# 1. 创建批次捕获 UUID BATCH_ID$(gog --account youexample.com batch begin --service docs --doc docId --name weekly update) # 2. 陆续追加操作支持 docs write/update/insert/delete/format/cell-style 等可直接组合的变更 gog --account youexample.com docs insert docId Status: ready --index 1 --batch $BATCH_ID gog --account youexample.com docs format docId --match Status: ready --bold --batch $BATCH_ID # 3. 检查批次的 wire 载荷 gog batch show $BATCH_ID --json # 4. 干跑验证不真正提交 gog --dry-run batch end $BATCH_ID --json # 5. 原子提交 gog batch end $BATCH_ID关于提交阶段的三个要点详见 docs/docs-batch.md 与 gog batch end默认gog batch end是原子提交一次 revision-locked 的documents.batchUpdate调用最多 500 个请求要么全部生效要么全部不生效--auto-split以非原子方式按最多 500 个请求的有序分块提交--continue-on-error在原子校验失败HTTP 400后逐个提交并保留失败请求——二者互斥后续排队的追加操作会校验“批次身份”service、doc、account、client 必须一致见ValidateIdentityinternal/docsbatch/repository.go与“revision 一致性”不一致时以ErrIdentityMismatch/ErrRevisionChanged拒绝从机制上避免把编辑应用到错误的文档或过期的版本。追加时 revision 的语义是队列中第一条变更记录该文档当时的 revision后续请求必须携带相同 revision 才能入队提交时通过writeControl.requiredRevisionId携带该 revision确保请求针对的是同一个文档版本wire 载荷组装见 internal/cmd/docs_batch_store.go。七、注意事项与适用边界只有“可直接组合”的 Docs 变更支持--batch包括docs write必须是批次中第一条、docs update、docs insert、docs delete、docs format、docs cell-style、docs table-column-width、docs insert-person、docs insert-file-chip、docs insert-date-chip、docs insert-page-break。Markdown 写入、页面布局、插图、建表等多阶段操作被刻意排除因为它们会在写入之间执行读取或副作用无法诚实地共享一次原子 Docs API 请求位置解析针对“当时的线上文档”范围、锚点、tab、文末位置在每条命令排队时即时解析不会在本地重放先前已排队的请求。官方建议优先使用稳定的显式索引若必须按相对位置排队从文档末尾向开头逐个排队更安全begin不带--doc会直接报错源码中strings.TrimSpace(c.DocID) 即返回empty --doc清理机制batch abort batchId丢弃批次batch prune --older-than 72h清理超过 72 小时未更新的陈旧批次默认阈值定义在BatchPruneCmd的OlderThan字段见 internal/cmd/batch.go。八、测试验证与可靠性的源码佐证本仓库用大量测试锁定了批次行为的正确性可作为阅读与二次开发的入口internal/cmd/docs_batch_store_test.go例如TestBatchEndAtomicSubmitsExactPayloadAndDeletesState用httptest服务端断言提交路径为/documents/doc1:batchUpdate、载荷携带writeControl.requiredRevisionId且提交完成后批次文件被删除TestBatchEndAutoSplitChainsRevision验证--auto-split时每个分块会串联下一块所需的最新 revisioninternal/docsbatch/repository_test.go覆盖仓库层Create → Append → Get → List → Prune的完整生命周期并用可注入的Now/NewID函数固定时间与 UUID验证created_at、updated_at、required_revision_id等字段的精确写入。这些测试同时印证了文章前述的约定批次是“持久化 revision 锁定 原子提交”三者的结合begin正是这套机制在命令行上的统一入口。相关文档gog batch命令族总览gog batch end提交与恢复模式Google Docs request batches完整设计文档Paths and State状态目录说明命令索引【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考