gogcligog api describe命令详解在终端中深入探索 Google Discovery API 与方法的完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog api describe是 gogcliGoogle Workspace in your terminal中用于内省 Google Discovery API的核心命令给定 API 名称与版本号即可在终端中查看该 API 的完整能力清单标题、文档链接、全部方法并可按方法 ID 进一步查看单个方法的参数、HTTP 动词与 OAuth 作用域等元数据。阅读本文后你将掌握该命令的全部位置参数、输出结构、全局 Flags 的语义以及其背后的 Discovery 文档获取、24 小时磁盘缓存与服务端回退机制能够把它与gog api list、gog api call组合成一条先探索、再调用的完整工作流。命令定位gog api家族中的内省者gog api子命令组在 gogcli 中承担通用 Google API 访问职责其下有三个子命令定义见 internal/cmd/api.gogog api list——列出 Google Discovery API 目录默认仅列出 preferred 版本可用--all包含非首选版本gog api describe本文主角——描述某个 Discovery API 或其中的单个方法gog api call——直接调用某个由 Discovery 描述的方法以 OAuth 作用域自动选择、路径/查询参数拼接为核心。三者共享同一份 Discovery 文档读取与缓存基础设施describe负责读懂 APIcall负责使用 APIlist负责发现 API。这与 gogcli 提供的大量一等公民命令如gog gmail ...、gog drive ...互为补充——当你需要访问尚未提供专有命令的 Google API 时gog api家族就是通用逃生通道。使用语法与位置参数gog api describe api version [method] [flags]位置参数必填含义api是Discovery API 名称例如gmail、drive、calendarversion是Discovery API 版本例如v1、v3method否可选的 Discovery 方法 ID例如gmail.users.labels.list对应源码结构见 internal/cmd/api.go 中APIDescribeCmd的定义API与Version为必填位置参数Method标记为optional。命令自身独有的 Flags 只有--no-cacheNoCache bool其余均为 gogcli 全局 Flags。不带method查看整个 API 的摘要省略方法 ID 时命令返回一个 JSON 对象包含四个字段见 internal/cmd/api.goname——API 名称version——API 版本title——API 的展示标题documentation_link——Google 官方文档链接methods——按方法 ID 排序后的全部方法列表。例如gog api describe gmail v1输出结构示意{ name: gmail, version: v1, title: Gmail API, documentation_link: https://developers.google.com/gmail/api, methods: [ { id: gmail.users.drafts.create, resource: users.drafts, name: create, spec: { httpMethod: POST, path: gmail/v1/users/{userId}/drafts, ... } } ] }这里的methods数组由discoveryapi.Methods()生成internal/discoveryapi/discovery.go它把 Discovery 文档中顶层methods与嵌套resources中的方法递归拍平为每个方法补齐id若缺失则用resource.name拼接最后按 ID 字典序排序保证输出稳定、便于脚本 diff。带method查看单个方法的完整规格传入方法 ID 后命令通过discoveryapi.FindMethod()internal/discoveryapi/discovery.go精确匹配方法并直接输出该方法的 JSON 规格Method结构见 internal/discoveryapi/discovery.gogog api describe gmail v1 gmail.users.labels.list{ id: gmail.users.labels.list, resource: users.labels, name: list, spec: { id: gmail.users.labels.list, httpMethod: GET, path: gmail/v1/users/{userId}/labels, parameters: { userId: { location: path, required: true, type: string }, maxResults: { location: query, type: integer, default: 100 } }, scopes: [https://www.googleapis.com/auth/gmail.readonly] } }FindMethod同时接受完整 ID如gmail.users.labels.list或resource.name形式如users.labels.list匹配到即返回找不到时返回discovery method not found错误。方法未命中时APIDescribeCmd.Run会将其包装为 usage 错误返回internal/cmd/api.go。这些字段正是gog api call组装真实 HTTP 请求所需的全部信息httpMethod决定请求动词path中的{param}与param占位符由路径参数填充parameters决定必填校验与查询串构造scopes用于选择 OAuth 作用域详见 internal/discoveryapi/discovery.go 的BuildURL。因此describe输出的方法规格本质上就是call的可执行蓝图。Flags 全表与 gogcli 其他命令一致gog api describe继承了完整的全局 Flags 体系。以下为命令文档docs/commands/gog-api-describe.md中登记的全部 FlagsFlag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时后过期-a--account--acctstring用于已认证 Google API 命令的账号邮箱、别名或 auto--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 配置/数据/状态/缓存根目录等价于 GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-cachebool获取 Discovery 文档时不读写 24 小时磁盘缓存--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 作用域--results-onlyboolJSON 模式下仅输出主要结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径。多数命令推荐使用 --fields-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中为抓取到的文本字段包裹外部不可信内容标记Flags 解读要点--no-cache是本命令的关键开关它绕过 Discovery 文档的 24 小时磁盘缓存强制向远程获取最新文档。调试为什么 describe 出的方法与线上不一致时优先检查它。其余全局 Flags 由 gogcli 根命令注入RootFlags例如命令启用/禁用策略--enable-commands/--disable-commands在 internal/cmd/api.go 的enforceDiscoveryMethodPolicy中还会以api.method-id点路径形式对gog api call生效保证通用调用也受 CLI 白名单约束。--json/--plain双输出模式虽然describe本身即输出 JSON全局--json等价于--machine与--plainTSV为脚本化消费提供了稳定、无装饰的输出通道--select支持点路径字段裁剪适合只取methods子集。--wrap-untrusted与--readonly是面向 Agent/LLM 场景的安全 Flags前者在 JSON/raw 输出中为远端返回的文本字段包裹不可信内容标记见 internal/cmd/api_test.go 对EXTERNAL_UNTRUSTED_CONTENT标记的测试后者从运行时层面拦截修改型请求。执行流程与源码走读APIDescribeCmd.Run的执行链路internal/cmd/api.go只有三步简洁而清晰获取 Discovery 文档调用discoveryDescriptionClient(ctx, c.NoCache).Description(ctx, c.API, c.Version)。discoveryDescriptionClientinternal/cmd/api.go在未指定--no-cache时会把缓存目录指向commandLayout中的cache/discovery子目录并挂载到 Discovery 客户端上。输出 API 摘要或查找方法若未提供method直接输出包含methods的摘要 JSON否则调用FindMethod精确匹配。写出结果统一经outfmt.WriteJSON写至 stdout。Client.Descriptioninternal/discoveryapi/discovery.go是核心实现其行为包括校验api、version非空否则返回ErrInvalidDescription构造请求 URL{base}/apis/{api}/{version}/rest默认 base 为https://www.googleapis.com/discovery/v1可用环境变量GOG_DISCOVERY_BASE_URL覆盖便于测试与代理场景启用缓存时先尝试读缓存命中则直接返回避免网络往返响应体以162016 MiB为上限流式读取超限或非 2xx 均返回错误成功后异步写入缓存若上下文尚未取消。Discovery 文档的 24 小时磁盘缓存--no-cache的反义词——默认行为——由 internal/discoveryapi/cache.go 实现缓存策略相当工程化TTLdescriptionCacheTTL 24 * time.Hour文件修改时间超过一天即视为失效键对请求 URL 做 SHA-256文件名形如sha256.json并通过descriptionCacheKey区分默认 base URL额外拼接service-hosted-fallback哨兵避免显式 base URL 复用服务端回退结果容量最多32个条目、总大小上限64 MiB、单条目上限16 MiB写入前会先清理过期/超限条目LRU 风格按 ModTime 排序淘汰并发跨进程写入用filelock.Shared的排他锁串行化锁等待上限 100ms锁竞争或文件系统错误一律当作缓存未命中处理绝不阻塞网络路径原子性先写.discovery-*临时文件再os.Rename落位。缓存命中与否有直接测试保障TestDiscoveryCommandCacheAndBypassinternal/cmd/api_test.go验证了两次 describe 只发一次网络请求describe 与 call 共享同一份缓存--no-cache强制重新拉取三个行为。服务端回退Service-Hosted Discovery当默认 Discovery 端点返回 404 且使用默认 base URL 时客户端会回退到服务自身托管的 Discovery 文档https://{service}.googleapis.com/$discovery/rest?version{version}internal/discoveryapi/discovery.go。回退前的服务名会经过严格的合法性校验小写字母/数字/连字符、长度不超过 63、不以连字符开头结尾防止拼凑出恶意主机名。测试 internal/discoveryapi/discovery_test.go 演示了meet v2的完整回退链路并断言自定义 base URL 不触发回退非 404 错误不触发回退等边界。典型使用场景场景一先 list 发现再 describe 深入# 查看 Discovery API 目录只看 preferred 版本 gog api list # 深入某个 API拿到全部方法清单 gog api describe drive v3 # 精确定位单个方法的规格 gog api describe drive v3 drive.files.list场景二为gog api call做准备# 确认方法名、参数与作用域 gog api describe calendar v3 calendar.events.list --json --select spec.parameters # 直接把 describe 得到的方法规格作为 call 的参数依据 gog api call calendar v3 calendar.events.list --params {calendarId:primary,maxResults:10}注意gog api call对非只读方法要求显式--allow-write且受命令策略--enable-commands/--disable-commands、--readonly、Gmail no-send 等安全机制约束见 internal/cmd/api.godescribe阶段先看清方法的httpMethod与scopes是规避误写操作的有效前置步骤。场景三脚本与 Agent 场景# 机器可读输出配合 jq 提取方法 ID 列表 gog api describe gmail v1 --json | jq -r .methods[].id # CI 中无需交互且绕过缓存获取最新文档 gog api describe gmail v1 --no-cache --no-input --jsondescribe是纯只读命令仅 GET Discovery 文档配合--no-input可安全地用于 CI 与自动化流水线--wrap-untrusted则适合 LLM Agent 消费输出时区分可信 CLI 元数据与远端返回内容。常见问题与使用建议输出太大怎么办不带method时methods数组可能很长优先用--select或--json 外部jq裁剪字段或直接指定method只看单个方法。想要最新文档使用--no-cache注意它同时跳过缓存写入频繁使用会失去缓存加速单次请求受 30s HTTP 超时与 16 MiB 响应上限约束见 internal/discoveryapi/discovery.go。方法找不到先确认版本号正确可用gog api list --all核对再确认方法 ID 形式为resource.name或完整idFindMethod对两者均支持。文档页从哪来docs/commands/gog-api-describe.md 页首注明该页由gog schema --json生成不应手工编辑而是通过make docs-commands重新生成——这意味着本文中的 Flags 表与命令帮助文本始终与源码定义保持同步。总而言之gog api describe是 gogcli 中把Google 的 Discovery 元数据翻译成可读、可脚本化、可执行的枢纽命令向上承接gog api list的目录发现向下为gog api call提供精确的方法蓝图同时通过 24 小时缓存、服务端回退与全局安全 Flags把通用 API 访问的探索体验做得既快又稳。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考