gogcligog calendar raw实战指南无损获取 Google Calendar 事件原始 JSON 响应【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文以 gogcli 的 gog-calendar-raw 命令参考为主体讲解gog calendar raw这条命令的定位、用法与全部参数并结合 internal/cmd/calendar_raw.go 的源码实现深入剖析它如何完成日历选择器解析、事件 ID 归一化支持从网页链接直接提取 ID以及无损 JSON 输出。读完本文你能够在脚本、调试与 LLM 工作流中稳定地拿到与 Google Calendar API 返回完全一致的事件对象并理解其背后的实现细节与安全注意事项。命令定位为脚本与 LLM 准备的无损 JSON 出口gog calendar raw的定位由命令自身的一句话说明即可概括见 docs/commands/gog-calendar-raw.mdDump raw Google Calendar API response as JSON (Events.Get; lossless; for scripting and LLM consumption)也就是说它调用 Google Calendar API 的Events.GetREST 参考为 docs/commands/gog-calendar-raw.md 中标注的 events/get 端点把完整的原始响应原样转储为 JSON而不是像gog calendar event那样输出经过筛选、格式化的表格视图。这一设计与 gogcli 中gog service raw系列命令的整体哲学一致——docs/raw-api.md 明确说明当脚本需要 gog 尚未建模的字段或需要“Google 原样返回的 API 对象”进行调试时就应使用 raw 命令。calendar raw是该系列的一员同族还有 gog-contacts-raw、gog-gmail-raw、gog-sheets-raw 等。“lossless无损”是这个命令的关键承诺响应中的attendees、extendedProperties、reminders等字段都会原样出现在输出里。测试用例 internal/cmd/calendar_raw_test.go 中的TestCalendarRaw_HappyPath正是为此而设mock 服务返回一个带attendees数组的事件断言输出的 JSON 中既保留了id也保留了attendees字段——这正是普通表格输出会丢弃的信息。用法与位置参数命令签名为gog calendar (cal) raw calendarId eventId [flags]注意calendar支持缩写cal。两个位置参数的定义见 internal/cmd/calendar_raw.go 的CalendarRawCmd结构体位置参数kong 名称说明calendarIdcalendarId日历 ID例如primary、一个邮箱地址如共享日历/团队日历的邮箱或一个完整的日历 IDeventIdeventId事件 ID--prettypretty格式化输出 JSON默认是紧凑单行便于脚本解析与calendar家族其他命令不同的是raw命令不接受省略 calendarId 的默认值——在源码中它调用resolveCalendarSelector(ctx, store, svc, c.CalendarID, false)时把defaultPrimary传为false见 internal/cmd/calendar_raw.go因此必须显式给出日历标识例如gog calendar raw primary 1a2b3c4d5e6f7g8h9i0j gog calendar raw myteamgmail.com 1a2b3c4d5e6f7g8h9i0j --pretty完整 Flags 参考以下参数表完整继承自 docs/commands/gog-calendar-raw.md该页由gog schema --json生成通过make docs-commands刷新。除命令自有的--pretty外其余均为 gogcli 全局根参数Flag类型默认说明--access-tokenstring直接使用提供的 access token绕过已存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring账号邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth 客户端名称选择对应的存储凭据 token 桶--colorstringauto颜色输出auto|always|never--disable-commandsstring禁用命令列表逗号分隔支持点路径-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以 JSON 输出到 stdout最适合脚本--no-input/--non-interactive/--noninteractivebool绝不提示失败即报错适合 CI-p/--plain/--tsvboolfalse输出稳定、可解析的纯文本TSV无颜色--prettybool格式化 JSON默认紧凑单行——本命令独有--quota-projectstring计费 API 用量的 Google Cloud 项目作为 X-Goog-User-Project 发送部分 API 在使用 --access-token 或 ADC 时必需--readonlyboolfalse运行时阻断变更类 API 请求auth add 同时请求只读 OAuth 范围--results-onlyboolJSON 模式下仅输出主结果去掉 envelope 字段如 nextPageToken--select/--pick/--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径。首选方案多数命令用 --fields-v/--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/raw 输出中将抓取的文本字段包裹在“外部不可信内容”标记中对calendar raw而言最常用的是--pretty人类阅读-a/--account多账号环境下选择账号--wrap-untrusted把输出喂给 LLM/Agent 时的安全选项下文详述。源码走读一次 raw 请求的完整链路internal/cmd/calendar_raw.go 的Run方法只有约 30 行但覆盖了 raw 命令的全部关键行为按顺序拆解func (c *CalendarRawCmd) Run(ctx context.Context, flags *RootFlags) error { eventID : normalizeCalendarEventID(c.EventID) // 1. 事件 ID 归一化 if eventID { return usage(empty eventId) } account, err : requireAccount(flags) // 2. 确定账号 ... svc, err : calendarService(ctx, account) // 3. 构建 Calendar API 客户端 ... calendarID, err : resolveCalendarSelector(ctx, store, svc, c.CalendarID, false) ... // 4. 解析日历选择器 event, err : svc.Events.Get(calendarID, eventID).Context(ctx).Do() ... // 5. 调用 Events.Get event, err requireRawResponse(event, event not found) ... // 6. 空响应防护 return writeRawJSON(ctx, event, c.Pretty) // 7. 原样输出 JSON }第 1 步事件 ID 归一化——可以直接粘贴网页链接normalizeCalendarEventIDinternal/cmd/webid.go允许eventId参数是一个日历网页 URL 而不仅是裸 ID。它的解析规则仅处理 host 为calendar.google.com去掉www.前缀的 URL查询参数形式读取eid参数该值通常是 base64URL 编码含或不含 padding编码的eventId calendarId字符串解码后取第一个字段作为事件 ID见 internal/cmd/webid.go 与decodeBase64URLString路径形式匹配https://calendar.google.com/calendar/u/0/r/eventedit/eventId这类编辑链接取eventedit后的路径段见 internal/cmd/webid.go若不是可识别的 calendar.google.com 链接则原样返回输入即按裸 ID 处理。因此下面的写法是等价的gog calendar raw primary abc123def456 gog calendar raw primary https://calendar.google.com/calendar/u/0/r/eventedit/abc123def456这一归一化与calendar event等命令共用同一套日历解析辅助逻辑——CalendarRawCmd的注释也明确说明“short names, primary, and email aliases all work the same as they do forcalendar event”见 internal/cmd/calendar_raw.go。第 24 步账号与日历选择器解析requireAccount依据-a/--account确定当前账号支持邮箱、别名与 autocalendarService用该账号的凭据构建calendar.Service。日历选择器的解析在 internal/cmd/calendar_util.go 的resolveCalendarSelector中完成流程为prepareCalendarID同文件 L19-L34先做本地解析TrimSpace、空值检查此处defaultPrimaryfalse所以空输入直接报usage(empty calendarId)再通过配置存储store.ResolveCalendarID解析用户自定义的日历别名随后调用resolveCalendarID交给 API 侧进一步解析——primary、邮箱形式的共享日历等标识在此阶段得到最终确认。第 57 步API 调用与输出核心调用即svc.Events.Get(calendarID, eventID).Context(ctx).Do()对应 Calendar API v3 的Events.Get。两个辅助函数保证输出行为的稳健性internal/cmd/raw_helpers.gorequireRawResponseL10-L15API 客户端在某些异常下可能返回nil响应这里统一将其转为event not found错误避免后续 panicwriteRawJSONL17-L19委托给outfmt.WriteRaw按--pretty决定是否美化缩进不传--pretty时输出紧凑单行 JSON便于jq等工具消费。测试如何验证这套行为internal/cmd/calendar_raw_test.go 用httptest搭建的 mock Calendar 端点路径前缀/calendar/v3与真实 REST 路径/calendars/{calId}/events/{evId}一致见 L18-L30验证了四类场景测试场景断言TestCalendarRaw_HappyPath正常 200 返回完整事件输出是合法 JSONid正确且attendees字段无损保留TestCalendarRaw_APIError服务端 500Run返回错误TestCalendarRaw_NotFound404Run返回错误TestCalendarRaw_EmptyEventID空 eventIdRun返回 usage 错误mock 服务器对/users/me/calendarList返回空列表使解析器把输入日历视为字面量 ID——这从侧面印证了选择器解析会先走 calendarList 查询。安全与自动化建议raw 输出包含敏感字段raw 命令“刻意少加意见”docs/raw-api.md Safety Model 一节因此gog calendar raw的输出可能包含参会人邮箱、事件描述中的自由文本、会议链接等敏感内容。据此仓库文档给出的实践建议对 calendar 场景同样适用脚本优先-j/--jsonraw 命令天然输出 JSON--json用于统一 envelope 行为人类阅读优先--pretty当输出要粘贴进 LLM 或 Agent 上下文时加--wrap-untrusted它会保留 ID 与 URL同时把抓取的自由文本字段包裹在“外部不可信内容”标记中降低提示注入面能不落盘/不进日志就不要落盘/进日志——raw 输出是该对象在 Google API 侧的完整 payload结合--readonly可以在运行时确保只读语义raw 本身是 GET 请求不会修改日历该开关主要服务于组合式工作流中的整体安全约束。需要注意的边界本文示例基于当前仓库的calendar/v3端点实现事件 ID 与日历 ID 的解析行为以 internal/cmd/webid.go 与 internal/cmd/calendar_util.go 的现行代码为准eid参数的 base64 解码同时尝试无 paddingRawURLEncoding与带 paddingURLEncoding两种编码。相关文档与源码命令参考docs/commands/gog-calendar-raw.md本页由gog schema --json生成父命令docs/commands/gog-calendar.md命令索引docs/commands/README.mdraw 命令族总览与安全模型docs/raw-api.md命令实现internal/cmd/calendar_raw.goID 归一化internal/cmd/webid.go日历选择器解析internal/cmd/calendar_util.goraw 输出辅助函数internal/cmd/raw_helpers.go测试用例internal/cmd/calendar_raw_test.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考