gogcligog api call实战指南用 Google Discovery API 在终端调用任意 Google 服务方法【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog api call是 gogcliGoogle Workspace in your terminal中面向通用 Google API 调用的底层命令它不针对某个具体服务写死逻辑而是通过 Google 官方 Discovery 文档Discovery Document动态获取任意 API 的接口定义从而调用包括 Gmail、Drive、Calendar 在内的数百个 Google 服务方法。读完本文你将掌握gog api call的完整用法、全部参数语义、请求组装与安全防护机制以及如何与gog api list、gog api describe组合在没有一等公民命令覆盖的场景下完成自定义 API 操作。命令概览与定位gog api call api version method [flags]apiDiscovery API 名称例如gmail、drive、calendarversionAPI 版本例如v1、v3methodDiscovery 方法 ID例如gmail.users.labels.list、drive.files.list。gog api call属于 gog api 命令组与其同组的还有 gog api list列出 Google Discovery API和 gog api describe描述某个 API 或方法的完整签名。三者配合即可完成查 API → 看签名 → 发起调用的完整链路。从源码结构看该命令在 internal/cmd/api.go 中定义为APICallCmd其执行流程是拉取 Discovery 文档 → 定位方法 → 校验参数并组装 URL → 应用安全策略 → 发起 HTTP 请求 → 格式化输出。一条命令的完整执行链路理解gog api call的底层原理有助于准确使用它。以 APICallCmd.Run 为参照一次调用的内部流程如下获取 Discovery 文档调用discoveryapi.Client.Description拉取api/version/rest的 Discovery 文档。默认基址为https://www.googleapis.com/discovery/v1见 discovery.go当标准 Discovery 服务返回 404 时会回退到服务商托管的https://api.googleapis.com/$discovery/rest?versionversion见 discovery.go。定位方法FindMethod按方法 ID 或资源.方法名在文档中查找目标方法discovery.go。解析--params--params必须是合法 JSON 对象否则报invalid --params JSON。随后BuildURL将参数区分为 path 参数替换进 URL 路径如{userId}与 query 参数拼接到查询串未知参数报unknown parameter缺失必填参数报missing required parameterdiscovery.go。组装请求体--body提供 JSON 请求体支持file语法从文件读取空值不发送请求体api.go。安全校验见下文安全防护小节。鉴权与发送通过NewHTTPClientForScopes按所选 scope 建立 HTTP 客户端校验重定向目标必须位于googleapis.com域名然后执行请求api.go。输出响应体有 64 MiB 上限保护maxDiscoveryResponseBytes非 2xx 状态码会被包装为HTTPStatusError输出api.go。完整 Flags 参考下表完整列出gog api call支持的全部参数依据 gog-api-call.md 整理Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过已存储的 refresh token令牌约 1 小时后过期-a--account--acctstring账户邮箱、别名或auto用于需要认证的 Google API 命令--allow-writebool允许非只读 HTTP 方法还需确认或配合--force--bodystringJSON 请求体或文件路径--clientstringOAuth 客户端名称选择已存储的凭据与令牌桶--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 的 config/data/state/cache 根目录等价于GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON适合脚本处理--no-cachebool拉取 Discovery 文档时不读取、不写入 24 小时磁盘缓存--no-input--non-interactive--noninteractivebool永不交互提示需要输入时直接失败适合 CI--paramsstring{}路径与查询参数的 JSON 对象-p--plain--tsvboolfalse向 stdout 输出稳定可解析的纯文本TSV无颜色--quota-projectstring计费的 Google Cloud 项目作为X-Goog-User-Project发送部分 API 在使用--access-token或 ADC 时必须指定--readonlyboolfalse运行时阻止变更类 API 请求auth add也会只请求只读 OAuth 范围--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--scopestringOAuth scope 覆盖默认取 Discovery 文档中最窄的 scope--select--pick--projectstringJSON 模式下按逗号分隔字段选择输出尽力而为支持点路径一般命令推荐用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalse在 JSON/原始输出中将获取到的文本字段包上外部不可信内容标记实战从只读查询到写操作只读 GET 请求以查询 Drive 文件列表为例GET 方法无需--allow-writegog api call drive v3 drive.files.list --params {pageSize: 10} --json--params中的pageSize属于 query 参数会被拼接到 URL 查询串--json输出结构化的 JSON便于用jq等工具继续处理。带路径参数与请求体调用 Calendar 的calendar.freebusy.queryPOST 方法但语义上是查询ReadOnlyRequestAllowed判定其可安全执行见 api_test.go 中query POST dry-run 允许的用例gog api call calendar v3 calendar.freebusy.query \ --body {timeMin:2026-09-01T00:00:00Z,timeMax:2026-09-02T00:00:00Z,items:[{id:primary}]}需要路径参数的方法如gmail.users.messages.get中的userId、idgog api call gmail v1 gmail.users.messages.get \ --params {userId:me,id:18c4f2ab3de5f6} --json--body支持从文件读取 JSON--body request.json文件内容必须是合法 JSON否则报--body must be valid JSON or file。写操作先声明再确认对于使用 POST/PUT/DELETE 等非只读 HTTP 方法的调用必须先显式声明gog api call gmail v1 gmail.users.messages.send \ --allow-write --body message.json执行非只读请求时命令还会要求交互确认在 CI 或自动化脚本中可配合-y/--force跳过确认。注意--allow-write只负责允许非只读方法破坏性操作仍需--force两者是独立的防线。Dry-run 预览任何调用都可用-n/--dry-run预览而不真正执行——命令会打印将要请求的 API、方法、HTTP 方法与 URL 并成功退出api.gogog api call gmail v1 gmail.users.messages.send --dry-run --allow-write --body message.json输出格式控制--json结构化 JSON最适合脚本-p/--plain稳定的 TSV 纯文本输出--results-onlyJSON 模式下丢弃nextPageToken等信封字段只保留主结果--select按字段挑选输出支持a.b.c点路径。响应体超过 64 MiB 时命令会直接失败errDiscoveryResponseTooLarge避免大响应撑爆内存。发现与调试list / describe 组合在不确定 API 名称或方法 ID 时先用gog api list查看可用 APIgog api list gog api list --all # 包含非 preferred 版本再用gog api describe查看 API 或具体方法的完整定义gog api describe gmail v1 # 列出 gmail v1 的所有方法 gog api describe gmail v1 gmail.users.labels.list # 查看单个方法的参数、路径、scopedescribe输出的方法定义参数 schema、HTTP 方法、scope 列表正是api call组装请求的依据两者共享同一套 Discovery 文档解析逻辑api.go。安全防护机制详解gog api call是绕过一等公民命令、直接打原始 API的通道因此内置了多层安全防线这在 internal/cmd/api.go 与 internal/cmd/api_test.go 中均有明确实现与测试佐证只读请求守卫HTTP 方法 readonly 双重检查非只读方法必须带--allow-write否则直接报错要求显式 opt-inmethod xxx uses POST; pass --allow-write to opt in若全局处于--readonly模式则无论是否--allow-write都拒绝执行返回ErrReadOnly。测试用例TestAPICallRequiresWriteOptIn、TestAPICallReadOnlyBlocksWriteBeforeAuth分别验证了这两条路径api_test.go。目标主机校验请求 URL 必须使用https且主机属于googleapis.com域否则报untrusted Discovery API URLHTTP 重定向同样受此校验约束validateDiscoveryRedirect防止 OAuth 凭据被发送到不可信主机discovery.go。测试TestAPICallRejectsNonGoogleTargetBeforeAuth、TestValidateDiscoveryRedirect覆盖了此逻辑。Gmail 发送守卫对gmail.users.messages.send与gmail.users.drafts.send两个方法会强制检查--gmail-no-send标志、配置文件gmail_no_send及按账户配置的 no-send 规则命中即阻止执行api.go。测试用例TestDiscoveryGmailSendHonorsNoSendFlag等验证了这些场景。命令策略过滤--enable-commands/--enable-commands-exact/--disable-commands同样作用于 Discovery 方法。方法会被映射为api.method-id形式的点路径参与匹配例如drive.files.delete对应api.drive.files.delete未显式授权时会被拒绝api.go测试见TestDiscoveryMethodPolicyRequiresExplicitPermission。此外在启用了 baked safety profile 的环境下api call会被直接禁用只能使用一等公民命令api.go。不可信内容标记开启--wrap-untrusted后返回的文本字段如text/plain响应或 JSON 中的文本会被包上EXTERNAL_UNTRUSTED_CONTENT标记帮助 Agent/LLM 识别外部不可信内容降低提示注入风险api.go测试见TestWriteDiscoveryResponseWrapsUntrustedText。Discovery 文档的 24 小时缓存gog api call、describe、list共享 Discovery 文档的磁盘缓存文档默认缓存 24 小时TTL缓存目录位于 gogcli 的 cache 根下discovery/子目录使用 SHA-256 文件名并设有 32 条条目与 64 MiB 总容量上限过期条目按 LRU 清理cache.go。缓存写入使用文件锁串行化跨进程安全。需要最新文档时传--no-cache绕过缓存直接拉取设置了GOG_DISCOVERY_BASE_URL环境变量时可用自定义 Discovery 服务测试中正是通过该变量注入本地 mock 服务器。缓存命中与否可通过-v详细日志观察相关行为由TestDiscoveryCommandCacheAndBypass测试验证api_test.go。Scope 自动选择逻辑调用方法需要 OAuth 授权时gog api call默认不要求你手动指定 scopediscoveryScopes会从 Discovery 文档列出的可用 scope 中自动挑选最窄的一个——具体评分规则为包含readonly的 scope 优先得分最低其次.file结尾的 scope其余全量 scope 得分最高api.go。该行为由测试TestDiscoveryScopesSelectsNarrowestAlternative验证在mail.google.com/、gmail.modify、gmail.readonly三者中会选中gmail.readonlyapi_test.go。若确实需要更宽或特定的权限可用--scope覆盖但 scope 必须是该方法 Discovery 文档中列出的值否则报scope ... is not listed for this Discovery method。常见错误与排查错误信息含义与对策method xxx uses POST; pass --allow-write to opt in非只读方法未声明--allow-write补上该参数untrusted Discovery API URL目标 URL 非https://*.googleapis.com检查 API 名称/版本拼写或GOG_DISCOVERY_BASE_URLinvalid --params JSON--params不是合法 JSON检查引号与逗号missing required parameter xxx必填 path/query 参数缺失用gog api describe api version method查看参数表unknown parameter xxx--params中包含了该 Discovery 方法不认识的参数Discovery method xxx requires explicit command-policy permission命令策略未放行按提示把api.xxx加入--enable-commandsscope ... is not listed for this Discovery method--scope不在该方法可用的 scope 列表内discovery method not found: xxx方法 ID 不存在先用gog api describe核对 ID 拼写小结gog api call是 gogcli 中通用性最强的最后一公里通道它把 Google Discovery 文档变成可即时调用的终端命令让任何未被一等公民命令覆盖的 Google API 方法都能以受控、安全、可脚本化的方式执行。使用时牢记三条主线用--params/--body组装请求、用--allow-write与确认机制守住写操作边界、用--json/--results-only/--select控制输出再配合 list/describe 完成方法发现即可把它无缝嵌入自动化工作流。延伸阅读gog api list、gog api describe、gog api、命令索引。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考