gogcli 指南用gog sheets datasource table检查 Connected Sheets 数据源表Extracts【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南围绕 gogcli 的gog sheets datasource table命令组展开它是 Google Workspace 终端工具 gogcli 中用于**检查 Connected Sheets连接工作表数据源表data-source table即 extracts**的只读能力入口提供list、describe、read三个子命令分别完成有哪些表、表的结构如何、表里的数据是什么三个问题。读完本文你将掌握数据源表与锚点单元格anchor cell的概念、三个子命令的完整用法与输出字段、底层 API 调用原理以及如何将命令接入 JSON/TSV 脚本化流程。命令定位Connected Sheets 数据源管理树的查看分支在 gogcli 的命令树中gog sheets datasource table是 gog sheets datasource 的子命令组同级的还有add、delete、describe、list、refresh、update。其中table专门面向**数据源表extracts**这一层一个数据源data source在电子表格中可能渲染出多张提取表每张表由锚点单元格定位。命令的完整语法含全部别名如下可从 命令参考文档 查到gog sheets (sheet) datasource (data-source,data-sources,connected-sheets) table (tables,extract,extracts) command从源码 internal/cmd/sheets_datasource.go 中的SheetsDataSourceTableCmd结构体可以看出别名体系的设计type SheetsDataSourceTableCmd struct { List SheetsDataSourceTableListCmd cmd: default:withargs help:List>gog sheets datasource table list spreadsheetId [flags]list扫描整张电子表格的网格数据找出所有带dataSourceTable定义的单元格并把它们按(sheetId, 行, 列)排序后输出。它只接受一个可选过滤参数参数类型说明--data-source-idstring只显示属于该数据源 ID 的表过滤逻辑在 internal/cmd/sheets_datasource.go 的SheetsDataSourceTableListCmd.Run中实现先全量收集再按item.DataSourceID dataSourceID原地过滤。表格输出列由sheetsDataSourceTableColumns定义ANCHOR、DATA_SOURCE_ID、SELECTION列选择类型、COLUMNS列数量、ROW_LIMIT、STATE、LAST_REFRESH、ERROR。JSON 输出结构{spreadsheetId: ..., tables: [ ... ]}每个 table 项包含anchor、sheetId、sheetTitle、dataSourceId、columnSelectionType、columns、rowLimit、state、lastRefreshTime、errorCode、errorMessage以及完整的dataSourceTable原始对象。当没有任何表时终端模式打印No Connected Sheets>{ dataSourceTable: { dataSourceId: ds-table, columnSelectionType: SELECTED, columns: [ {name: word}, {name: word_count} ], rowLimit: 5, dataExecutionStatus: { state: SUCCEEDED, lastRefreshTime: 2026-08-13T16:31:00Z } } }SELECTED表自带内联columns列表可配合rowLimit限制行数如上例明确列出word、word_count两列并限定 5 行SYNC_ALL不带内联列列表列定义存放在独立的 DATA_SOURCE 工作表上需要额外的请求才能拿到见下文read 的实现原理。dataExecutionStatus中的state反映最近一次数据执行的状态如SUCCEEDED、FAILEDlastRefreshTime给出刷新时间出错时还会带errorCode/errorMessage。这些字段正是list/describe输出的STATE、LAST_REFRESH、ERROR列的数据来源对应源码中的setSheetsDataExecutionStatus。table describe查看单张表的完整结构gog sheets datasource table describe spreadsheetId anchor # 或使用别名 gog sheets datasource table get spreadsheetId anchordescribe根据 anchor 精确定位一张表。实现上先按 anchor 做**范围限定ranged**的电子表格读取见fetchSheetsDataSourceTables中call.Ranges(anchor)再从结果中匹配findSheetsDataSourceTable若该 anchor 处没有表会返回data-source table not found at ...。文本输出tab 分隔的键值行anchor、dataSourceId、selection列选择类型、columns逗号连接的列名列表、rowLimit、state、lastRefreshTime出错时追加error行。JSON 输出{spreadsheetId, anchor, sheetId, sheetTitle, dataSourceTable}其中dataSourceTable是 Google Sheets API 的原始DataSourceTable对象包含列引用、行限制与执行状态的全部细节适合程序化解析。测试 TestSheetsDataSourceTableListDescribeAndRead 验证了describe connected1 Extracts!B3能返回columnSelectionType: SELECTED与dataSourceId: ds-table。table read读取表内的实际数据值gog sheets datasource table read spreadsheetId anchor [flags] # 或使用别名 gog sheets datasource table values spreadsheetId anchorread把提取表当作一个值区域来读是gog sheets中常用的数据提取命令其专属参数有参数类型默认值说明--max-rowsint1000最多读取的数据行数表头行单独返回、不计入上限必须大于 0--renderstringFORMATTED_VALUE取值渲染方式FORMATTED_VALUE、UNFORMATTED_VALUE或FORMULA源码中SheetsDataSourceTableReadCmd的定义确认了这两个参数与默认值type SheetsDataSourceTableReadCmd struct { SpreadsheetID string arg: name:spreadsheetId help:Spreadsheet ID Anchor string arg: name:anchor help:Table anchor cell including sheet name (for example Extract!A1) MaxRows int name:max-rows help:Maximum data rows to read (header row is returned separately) default:1000 ValueRenderOption string name:render help:Value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA default:FORMATTED_VALUE enum:FORMATTED_VALUE,UNFORMATTED_VALUE,FORMULA }read 的实现原理从 anchor 推导读取范围read并不直接调用读取数据源表专用接口而是先确定表占用的列数再把读取范围换算成普通 A1 区间后调用Spreadsheets.Values.Getinternal/cmd/sheets_datasource.go按 anchor 做 ranged 查找拿到表的行数上限RowLimit与列定义若表自带列列表SELECTED 形态列数直接取len(item.Columns)若列数为 0SYNC_ALL 形态则额外发起一次**非范围限定unranged**的spreadsheets.get从 DATA_SOURCE 工作表的dataSourceSheetProperties.columns里恢复列数对应fetchSheetsDataSourceSheetColumns注释明确说明ranged lookup 拿不到 SYNC_ALL 表的列列表行数取min(--max-rows, RowLimit)并计算truncated标记当表的RowLimit为 0无限制或大于--max-rows时输出truncated: true拼接范围anchor:end其中 end 由sheetsa1.FormatCell(sheetTitle, rowrows, columncolumnCount-1)计算以MajorDimension(ROWS)和指定的ValueRenderOption执行Values.Get。测试中的实例锚点Extracts!B3、2 列、--max-rows 3时实际请求的范围是Extracts!B3:C6表头 3 行数据并返回truncated: trueSYNC_ALL 场景下Synced Extract!A1读取得到Synced Extract!A1:B4。这些断言分别在TestSheetsDataSourceTableListDescribeAndRead与TestSheetsDataSourceTableReadSyncAllExtract中后者还专门验证了 SYNC_ALL 形态只会多发起一次列查询不会反复请求。JSON 输出结构{spreadsheetId, anchor, range, dataSourceId, state, truncated, values}其中values为二维数组含表头行。终端模式按行输出 tab 分隔的单元格值没有任何数据时打印No data found。全局 Flags所有子命令共享的通用选项三个子命令均继承 gogcli 的通用 flags与 gog sheets datasource 一致完整清单如下其中table read额外支持--max-rows与--render且不包含任何写操作相关标志无--dry-run冲突仍保留-n/--dry-run等只读预览语义Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过已存储的 refresh token令牌约 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 的 config/data/state/cache 根目录等价于GOG_HOME-j--json--machineboolfalse以 JSON 输出到 stdout最适合脚本处理--no-input--non-interactive--noninteractivebool永不提示失败直接报错适合 CI-p--plain--tsvboolfalse输出稳定、可解析的文本到 stdoutTSV无颜色--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 模式下选择逗号分隔的字段尽力而为支持点路径多数命令推荐使用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段用外部不可信内容标记包裹权限要求Connected Sheets 读取与bigquery.readonlyscope数据源表来自 BigQuery 等后端数据源gogcli 在源码中定义了所需的额外 OAuth scopeconst connectedSheetsBigQueryScope https://www.googleapis.com/auth/bigquery.readonly当 API 返回insufficient authentication scopes或access_token_scope_insufficient、insufficientpermissions等特征时wrapConnectedSheetsReadError会把错误包装成带修复指引的用户可读信息见 internal/cmd/sheets_datasource.go建议在保留现有--services选择的前提下重新认证并追加 scopegog auth add account --services sheets --extra-scopes https://www.googleapis.com/auth/bigquery.readonly --force-consent对应测试 TestWrapConnectedSheetsReadError 验证了普通权限错误如permission denied for BigQuery table会被原样保留只有 scope 不足类错误才触发该修复提示。脚本化实践把表数据接入自动化流程三个子命令天然适合脚本场景。结合-jJSON与--max-rows、--render可以像下面这样在终端或 CI 中完成枚举 → 查看结构 → 抽取数据的完整链路# 1. 列出某电子表格中属于指定数据源的所有提取表 gog sheets datasource table list spreadsheetId --data-source-id ds-table -j # 2. 查看某张表锚定在 Extracts!B3的结构 gog sheets datasource table describe spreadsheetId Extracts!B3 -j # 3. 读取前 100 行使用未格式化原始值适合数值运算 gog sheets datasource table read spreadsheetId Extracts!B3 --max-rows 100 --render UNFORMATTED_VALUE -j # 4. 非交互 只读模式适合 CI 环境 gog sheets datasource table read spreadsheetId Extracts!B3 --no-input --readonly -p几点实用的注意anchor 中含有空格或特殊字符的工作表名记得加单引号例如Synced Extract!A1源码测试中即为该写法--max-rows限制的是数据行数表头行单独返回、不计入上限需要完整数据时把--max-rows调大即可但要注意truncated: true标记代表结果已被行数限制截断脚本中应检查该字段判断数据是否取全希望得到稳定可解析的纯文本时使用-p/--plain/--tsv它会输出无颜色的 TSV读取仅涉及查询类操作可放心搭配--readonly与--no-input用于自动化巡检防止任何意外写操作。相关命令与进一步阅读父命令gog sheets datasource管理数据源与 extracts 的总入口同级操作gog sheets datasource add添加 BigQuery Connected Sheets 数据源、gog sheets datasource delete删除数据源及关联工作表、gog sheets datasource refresh刷新数据源、gog sheets datasource update更新数据源命令索引Command index源码与测试internal/cmd/sheets_datasource.go、internal/cmd/sheets_datasource_test.go、internal/cmd/testdata/sheets_connected_sheets.json【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
gogcli 指南用gog sheets datasource table检查 Connected Sheets 数据源表Extracts【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南围绕 gogcli 的gog sheets datasource table命令组展开它是 Google Workspace 终端工具 gogcli 中用于**检查 Connected Sheets连接工作表数据源表data-source table即 extracts**的只读能力入口提供list、describe、read三个子命令分别完成有哪些表、表的结构如何、表里的数据是什么三个问题。读完本文你将掌握数据源表与锚点单元格anchor cell的概念、三个子命令的完整用法与输出字段、底层 API 调用原理以及如何将命令接入 JSON/TSV 脚本化流程。命令定位Connected Sheets 数据源管理树的查看分支在 gogcli 的命令树中gog sheets datasource table是 gog sheets datasource 的子命令组同级的还有add、delete、describe、list、refresh、update。其中table专门面向**数据源表extracts**这一层一个数据源data source在电子表格中可能渲染出多张提取表每张表由锚点单元格定位。命令的完整语法含全部别名如下可从 命令参考文档 查到gog sheets (sheet) datasource (data-source,data-sources,connected-sheets) table (tables,extract,extracts) command从源码 internal/cmd/sheets_datasource.go 中的SheetsDataSourceTableCmd结构体可以看出别名体系的设计type SheetsDataSourceTableCmd struct { List SheetsDataSourceTableListCmd cmd: default:withargs help:List>gog sheets datasource table list spreadsheetId [flags]list扫描整张电子表格的网格数据找出所有带dataSourceTable定义的单元格并把它们按(sheetId, 行, 列)排序后输出。它只接受一个可选过滤参数参数类型说明--data-source-idstring只显示属于该数据源 ID 的表过滤逻辑在 internal/cmd/sheets_datasource.go 的SheetsDataSourceTableListCmd.Run中实现先全量收集再按item.DataSourceID dataSourceID原地过滤。表格输出列由sheetsDataSourceTableColumns定义ANCHOR、DATA_SOURCE_ID、SELECTION列选择类型、COLUMNS列数量、ROW_LIMIT、STATE、LAST_REFRESH、ERROR。JSON 输出结构{spreadsheetId: ..., tables: [ ... ]}每个 table 项包含anchor、sheetId、sheetTitle、dataSourceId、columnSelectionType、columns、rowLimit、state、lastRefreshTime、errorCode、errorMessage以及完整的dataSourceTable原始对象。当没有任何表时终端模式打印No Connected Sheets>{ dataSourceTable: { dataSourceId: ds-table, columnSelectionType: SELECTED, columns: [ {name: word}, {name: word_count} ], rowLimit: 5, dataExecutionStatus: { state: SUCCEEDED, lastRefreshTime: 2026-08-13T16:31:00Z } } }SELECTED表自带内联columns列表可配合rowLimit限制行数如上例明确列出word、word_count两列并限定 5 行SYNC_ALL不带内联列列表列定义存放在独立的 DATA_SOURCE 工作表上需要额外的请求才能拿到见下文read 的实现原理。dataExecutionStatus中的state反映最近一次数据执行的状态如SUCCEEDED、FAILEDlastRefreshTime给出刷新时间出错时还会带errorCode/errorMessage。这些字段正是list/describe输出的STATE、LAST_REFRESH、ERROR列的数据来源对应源码中的setSheetsDataExecutionStatus。table describe查看单张表的完整结构gog sheets datasource table describe spreadsheetId anchor # 或使用别名 gog sheets datasource table get spreadsheetId anchordescribe根据 anchor 精确定位一张表。实现上先按 anchor 做**范围限定ranged**的电子表格读取见fetchSheetsDataSourceTables中call.Ranges(anchor)再从结果中匹配findSheetsDataSourceTable若该 anchor 处没有表会返回data-source table not found at ...。文本输出tab 分隔的键值行anchor、dataSourceId、selection列选择类型、columns逗号连接的列名列表、rowLimit、state、lastRefreshTime出错时追加error行。JSON 输出{spreadsheetId, anchor, sheetId, sheetTitle, dataSourceTable}其中dataSourceTable是 Google Sheets API 的原始DataSourceTable对象包含列引用、行限制与执行状态的全部细节适合程序化解析。测试 TestSheetsDataSourceTableListDescribeAndRead 验证了describe connected1 Extracts!B3能返回columnSelectionType: SELECTED与dataSourceId: ds-table。table read读取表内的实际数据值gog sheets datasource table read spreadsheetId anchor [flags] # 或使用别名 gog sheets datasource table values spreadsheetId anchorread把提取表当作一个值区域来读是gog sheets中常用的数据提取命令其专属参数有参数类型默认值说明--max-rowsint1000最多读取的数据行数表头行单独返回、不计入上限必须大于 0--renderstringFORMATTED_VALUE取值渲染方式FORMATTED_VALUE、UNFORMATTED_VALUE或FORMULA源码中SheetsDataSourceTableReadCmd的定义确认了这两个参数与默认值type SheetsDataSourceTableReadCmd struct { SpreadsheetID string arg: name:spreadsheetId help:Spreadsheet ID Anchor string arg: name:anchor help:Table anchor cell including sheet name (for example Extract!A1) MaxRows int name:max-rows help:Maximum data rows to read (header row is returned separately) default:1000 ValueRenderOption string name:render help:Value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA default:FORMATTED_VALUE enum:FORMATTED_VALUE,UNFORMATTED_VALUE,FORMULA }read 的实现原理从 anchor 推导读取范围read并不直接调用读取数据源表专用接口而是先确定表占用的列数再把读取范围换算成普通 A1 区间后调用Spreadsheets.Values.Getinternal/cmd/sheets_datasource.go按 anchor 做 ranged 查找拿到表的行数上限RowLimit与列定义若表自带列列表SELECTED 形态列数直接取len(item.Columns)若列数为 0SYNC_ALL 形态则额外发起一次**非范围限定unranged**的spreadsheets.get从 DATA_SOURCE 工作表的dataSourceSheetProperties.columns里恢复列数对应fetchSheetsDataSourceSheetColumns注释明确说明ranged lookup 拿不到 SYNC_ALL 表的列列表行数取min(--max-rows, RowLimit)并计算truncated标记当表的RowLimit为 0无限制或大于--max-rows时输出truncated: true拼接范围anchor:end其中 end 由sheetsa1.FormatCell(sheetTitle, rowrows, columncolumnCount-1)计算以MajorDimension(ROWS)和指定的ValueRenderOption执行Values.Get。测试中的实例锚点Extracts!B3、2 列、--max-rows 3时实际请求的范围是Extracts!B3:C6表头 3 行数据并返回truncated: trueSYNC_ALL 场景下Synced Extract!A1读取得到Synced Extract!A1:B4。这些断言分别在TestSheetsDataSourceTableListDescribeAndRead与TestSheetsDataSourceTableReadSyncAllExtract中后者还专门验证了 SYNC_ALL 形态只会多发起一次列查询不会反复请求。JSON 输出结构{spreadsheetId, anchor, range, dataSourceId, state, truncated, values}其中values为二维数组含表头行。终端模式按行输出 tab 分隔的单元格值没有任何数据时打印No data found。全局 Flags所有子命令共享的通用选项三个子命令均继承 gogcli 的通用 flags与 gog sheets datasource 一致完整清单如下其中table read额外支持--max-rows与--render且不包含任何写操作相关标志无--dry-run冲突仍保留-n/--dry-run等只读预览语义Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过已存储的 refresh token令牌约 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 的 config/data/state/cache 根目录等价于GOG_HOME-j--json--machineboolfalse以 JSON 输出到 stdout最适合脚本处理--no-input--non-interactive--noninteractivebool永不提示失败直接报错适合 CI-p--plain--tsvboolfalse输出稳定、可解析的文本到 stdoutTSV无颜色--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 模式下选择逗号分隔的字段尽力而为支持点路径多数命令推荐使用--fields-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段用外部不可信内容标记包裹权限要求Connected Sheets 读取与bigquery.readonlyscope数据源表来自 BigQuery 等后端数据源gogcli 在源码中定义了所需的额外 OAuth scopeconst connectedSheetsBigQueryScope https://www.googleapis.com/auth/bigquery.readonly当 API 返回insufficient authentication scopes或access_token_scope_insufficient、insufficientpermissions等特征时wrapConnectedSheetsReadError会把错误包装成带修复指引的用户可读信息见 internal/cmd/sheets_datasource.go建议在保留现有--services选择的前提下重新认证并追加 scopegog auth add account --services sheets --extra-scopes https://www.googleapis.com/auth/bigquery.readonly --force-consent对应测试 TestWrapConnectedSheetsReadError 验证了普通权限错误如permission denied for BigQuery table会被原样保留只有 scope 不足类错误才触发该修复提示。脚本化实践把表数据接入自动化流程三个子命令天然适合脚本场景。结合-jJSON与--max-rows、--render可以像下面这样在终端或 CI 中完成枚举 → 查看结构 → 抽取数据的完整链路# 1. 列出某电子表格中属于指定数据源的所有提取表 gog sheets datasource table list spreadsheetId --data-source-id ds-table -j # 2. 查看某张表锚定在 Extracts!B3的结构 gog sheets datasource table describe spreadsheetId Extracts!B3 -j # 3. 读取前 100 行使用未格式化原始值适合数值运算 gog sheets datasource table read spreadsheetId Extracts!B3 --max-rows 100 --render UNFORMATTED_VALUE -j # 4. 非交互 只读模式适合 CI 环境 gog sheets datasource table read spreadsheetId Extracts!B3 --no-input --readonly -p几点实用的注意anchor 中含有空格或特殊字符的工作表名记得加单引号例如Synced Extract!A1源码测试中即为该写法--max-rows限制的是数据行数表头行单独返回、不计入上限需要完整数据时把--max-rows调大即可但要注意truncated: true标记代表结果已被行数限制截断脚本中应检查该字段判断数据是否取全希望得到稳定可解析的纯文本时使用-p/--plain/--tsv它会输出无颜色的 TSV读取仅涉及查询类操作可放心搭配--readonly与--no-input用于自动化巡检防止任何意外写操作。相关命令与进一步阅读父命令gog sheets datasource管理数据源与 extracts 的总入口同级操作gog sheets datasource add添加 BigQuery Connected Sheets 数据源、gog sheets datasource delete删除数据源及关联工作表、gog sheets datasource refresh刷新数据源、gog sheets datasource update更新数据源命令索引Command index源码与测试internal/cmd/sheets_datasource.go、internal/cmd/sheets_datasource_test.go、internal/cmd/testdata/sheets_connected_sheets.json【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
