
gogcli 查询 Sheet 命名区域gog sheets named-ranges get命令完整指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog sheets named-ranges get是 gogcliGoogle Workspace in your terminal提供的 Sheets 命名区域管理子命令之一用于按名称或 ID 精确读取某个命名区域Named Range的元数据与 A1 引用。本指南将带你掌握该命令的完整用法、全部参数与三种输出格式并结合仓库源码剖析其先拉取元数据目录、再按名称/ID 解析、最后格式化输出的底层实现链路适合需要将命名区域查询接入脚本、CI 或 LLM 工作流的开发者直接参考。命令定位与适用场景gog sheets named-ranges是一组用于管理电子表格命名区域的子命令集合包含五个操作gog sheets named-ranges add - 添加命名区域gog sheets named-ranges get - 查询命名区域gog sheets named-ranges list - 列出全部命名区域gog sheets named-ranges update - 更新命名区域gog sheets named-ranges delete - 删除命名区域其中get负责在已知区域名称如QuarterlyRevenue或区域 ID如nr123456的前提下快速反查该区域当前指向的工作表与行列范围。它在以下场景中尤为有用自动化校验脚本修改了命名区域的指向后用get核对新范围是否符合预期二次引用其他命令如公式写入、数据操作需要把命名区域解析为具体 A1 范围时先用get拿到可编程消费的结构化结果故障排查区域名称发生歧义或指向异常时用get快速确认元数据。基础用法根据 docs/commands/gog-sheets-named-ranges-get.md 的说明命令的标准调用形式为gog sheets (sheet) named-ranges (namedranges,nr) get (show,info) spreadsheetId nameOrId其中(sheet)与(namedranges,nr)表示父命令别名gog sheets与gog sheets sheet等价named-ranges、namedranges、nr三者等价get自带show、info两个别名三个词均可触发查询两个位置参数spreadsheetId与nameOrId均为必填。最小可运行示例按名称查询gog sheets named-ranges get spreadsheetId MyNamedRange使用别名与info等价gog sheet nr info spreadsheetId MyNamedRangenameOrId参数既可以是命名区域的名称也可以是 Google Sheets 分配的唯一 ID。从 源码实现 可以看出两个参数在 CLI 层都被定义为必填的位置参数arg:type SheetsNamedRangesGetCmd struct { SpreadsheetID string arg: name:spreadsheetId help:Spreadsheet ID NameOrID string arg: name:nameOrId help:Named range name or ID }全局 Flags 详解所有 gogcli 命令共享一套全局参数get命令同样完整继承。下表整理了 原文档 中的全部 Flags 及其在实际使用中的含义Flag类型默认值说明--access-tokenstring直接使用给定的访问令牌绕过本地存储的 refresh token令牌约 1 小时过期-a--account--acctstring指定账户邮箱、别名或auto用于已认证的 Google API 命令--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以 JSON 输出到 stdout最适合脚本处理--no-input--non-interactive--noninteractivebool永不提示直接失败适合 CI 环境-p--plain--tsvboolfalse输出稳定的可解析文本TSV无颜色--quota-projectstring用于计费的 Google Cloud 项目作为X-Goog-User-Project发送部分 API 在--access-token或 ADC 模式下要求--readonlyboolfalse运行时阻止所有修改型 API 请求auth add也会申请只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径多数命令推荐改用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中用外部不可信内容标记包裹抓取的文本字段对get这类只读命令来说最常用的组合是gog sheets named-ranges get spreadsheetId MyRange -a auto -j-a auto自动选择已认证账户-j以 JSON 输出便于jq等工具消费。输出格式文本与 JSONget命令的输出由 namedRangeItem 结构体 驱动它完整承载了命名区域的元数据type namedRangeItem struct { Name string json:name NamedRangeID string json:namedRangeId SheetID int64 json:sheetId SheetTitle string json:sheetTitle StartRowIndex int64 json:startRowIndex EndRowIndex int64 json:endRowIndex StartColIndex int64 json:startColumnIndex EndColIndex int64 json:endColumnIndex A1 string json:a1 }默认文本输出不指定任何输出参数时命令逐行打印四个关键字段源码gog sheets named-ranges get spreadsheetId MyNamedRange输出示例name MyNamedRange id nr123456 sheet Sheet1 a1 Sheet1!A1:B2sheet是命名区域所在工作表的标题a1是由internal/sheetsa1包把 GridRange零基的行列索引换算为人类可读 A1 记法的结果格式化为工作表名!起始单元格:结束单元格。JSON 输出-jgog sheets named-ranges get spreadsheetId MyNamedRange -j返回的结构为{ namedRange: { name: MyNamedRange, namedRangeId: nr123456, sheetId: 1, sheetTitle: Sheet1, startRowIndex: 0, endRowIndex: 1, startColumnIndex: 0, endColumnIndex: 1, a1: Sheet1!A1:B2 } }注意 JSON 模式下的行列索引是零基的 GridRange 索引startRowIndex等而a1字段是经过1换算后的基于 1 的坐标两者并存是为了兼顾机器精确性与人工可读性。对编程消费而言namedRangeId、sheetId和四个索引字段是最可靠的主键对人工核对而言直接看a1即可。JSON 模式下还可叠加--results-only去掉信封结构或使用--select挑选字段。实现原理按名称或 ID 的解析链路get之所以能同时接受名称与 ID是因为它在底层走了一条元数据目录 选择器解析的完整链路核心实现在 internal/cmd/sheets_named_ranges.go账户与参数校验通过requireAccount(flags)解析账户normalizeGoogleID规范化spreadsheetIdspreadsheetId与nameOrId任一为空即返回 usage 错误empty spreadsheetId/empty nameOrId。拉取范围目录调用fetchSpreadsheetRangeCatalog向 Google Sheets API 发起一次Spreadsheets.Get元数据请求。解析目标区域调用resolveNamedRangeByNameOrID匹配命名区域。格式化输出将匹配到的*sheets.NamedRange转换为namedRangeItem后按文本或 JSON 输出。元数据目录的按需拉取sheets_range_resolve.go 显示目录拉取使用字段过滤googleapi.Field只获取必要数据避免把整张表的值都拉回本地fields : googleapi.Field(sheets(properties(sheetId,title,index,gridProperties(rowCount,columnCount))),namedRanges(namedRangeId,name,range)) call : svc.Spreadsheets.Get(spreadsheetID).Fields(fields)返回的spreadsheetRangeCatalog同时维护了两张映射表SheetIDsByTitle与SheetTitlesByID后续把命名区域中的sheetId数字还原为工作表标题字符串时直接查表即可这也是输出中sheet与a1字段能准确生成的前提。名称/ID 的解析策略resolveNamedRangeByNameOrID 与 selectorutil/match.go 共同实现了三层匹配策略精确 ID 匹配先遍历所有命名区域若nameOrId与某个namedRangeId完全相等直接命中ID 优先且唯一大小写不敏感的名称匹配ID 未命中时使用strings.EqualFold对名称做忽略大小写的精确匹配歧义处理若大小写不敏感的名称匹配到多个区域命令不会静默选择而是返回错误并列出所有候选名称与 ID 对提示ambiguous named range让用户改用 ID 精确定位。匹配失败时统一返回unknown named range %q的 usage 错误。这套策略意味着名称大小写不必完全一致但 ID 必须精确名称存在歧义时会被显式拒绝。A1 记法的生成namedRangeItem.A1由 internal/sheetsa1/format.go 的FormatGridRange生成。该函数把零基的 GridRange 索引换算为基于 1 的 A1 记法简单工作表名^[A-Za-z0-9_]$直接使用Sheet1!前缀含空格等特殊字符的工作表名自动加单引号包裹如My Data!内部单引号做双写转义全列范围如Sheet1!A:C、整行范围如Sheet1!1:3以及单单元格如Sheet1!A1均有对应的 A1 表示。因此get输出的a1与你在 Google Sheets 界面中看到的命名区域引用完全一致可直接复制回表格或传给其他命令。与兄弟命令的配合get是命名区域工作流中的读操作与写操作配合可构成完整的生命周期管理创建后核对gog sheets named-ranges add spreadsheetId name range创建后用get验证返回的namedRangeId与换算后的a1是否准确更新前备份update之前先用get记录当前指向便于回滚删除前确认delete需要名称或 ID拿不准时先get确认目标避免误删批量巡检先用gog sheets named-ranges list spreadsheetId拿到全量列表再逐个get提取 A1 细节。从 源码结构 可以看到五个子命令统一挂在SheetsNamedRangesCmd下其中add/update/delete三个写操作会先经过dryRunExit检查支持--dry-run预览get/list为纯只读操作配合--readonly标志可放心地在受管环境中运行type SheetsNamedRangesCmd struct { List SheetsNamedRangesListCmd cmd: default:withargs help:List named ranges Get SheetsNamedRangesGetCmd cmd: name:get aliases:show,info help:Get a named range Add SheetsNamedRangesAddCmd cmd: name:add aliases:create,new help:Add a named range Update SheetsNamedRangesUpdateCmd cmd: name:update aliases:edit,set help:Update a named range Delete SheetsNamedRangesDeleteCmd cmd: name:delete aliases:rm,remove,del help:Delete a named range }测试与验证仓库在 internal/cmd/sheets_named_ranges_test.go 中提供了针对命名区域子命令的 HTTP mock 测试覆盖add校验 AddNamedRange 请求的 name、sheetId 与行列范围、update校验仅更新fields: name且携带正确的 namedRangeId、delete校验 DeleteNamedRangeRequest 的 ID。测试通过httptest.NewServer伪造 Sheets API 响应验证了 gogcli 生成的请求负载与真实 API 契约一致这也从侧面印证了get所依赖的目录拉取Spreadsheets.Get与解析逻辑在真实请求链路中的可靠性。list命令在 sheets_named_ranges.go 中还会对结果按名称、ID做稳定排序保证多次运行输出可比较这一点在对比list与get的结果时很有用。常见错误与排查empty spreadsheetId/empty nameOrId位置参数缺失或传入了空字符串检查命令是否缺少参数或参数是否被 shell 展开为空unknown named range xxx名称或 ID 在指定工作表中不存在。Google Sheets 的命名区域名称不能像 A1 引用那样跨命令做模糊匹配需确认名称拼写ambiguous named range xxx多个区域名称大小写不同但忽略大小写后相同改用精确 ID 查询get spreadsheet metadata: ...目录拉取失败通常是账户对该工作表无访问权限或spreadsheetId不合法可通过gog auth list与gog auth status检查认证状态参见 gog-auth-statusShell 转义问题某些 shell 会把!转义为\!导致解析异常cleanRange见 internal/cmd/sheets.go会自动把\!还原为!但传参时仍建议对特殊字符加引号。小结gog sheets named-ranges get是 gogcli 中用于精确读取命名区域元数据的只读命令它支持名称与 ID 双模式定位、区分大小写不敏感的匹配策略、显式拒绝歧义并能同时输出人工友好的 A1 记法与机器友好的零基索引 JSON。理解其元数据目录 → 选择器解析 → A1 换算的实现链路sheets_named_ranges.go、sheets_range_resolve.go、internal/sheetsa1/format.go可以让你在自动化脚本与 LLM 工作流中可靠地消费命名区域信息。更多命令请参考 命令索引。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考