gogcli 实战：用 `gog sheets datasource update` 更新 BigQuery Connected Sheets 数据源

gogcli 实战用gog sheets datasource update更新 BigQuery Connected Sheets 数据源【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文深入讲解 gogcli 中gog sheets datasource update命令的完整用法与底层实现。该命令用于对一个已存在的 BigQuery Connected Sheets 数据源执行部分更新Partial Update可替换查询 SQL、原生表定位信息或计费执行项目且只改动你明确指定的字段。读完本文你将掌握该命令的全部参数含义、字段掩码生成规则、安全性保护机制预检验证、dry-run、readonly、禁止自动重试以及通过源码与测试验证的实际调用链能够安全地在生产环境中修改 Connected Sheets 数据源。命令概览与定位gog sheets datasource update隶属于gog sheets datasource命令组管理 Connected Sheets 数据源与提取表与add、delete、list、describe、refresh、table并列。从 sheets_datasource.go 的源码结构看update子命令的定义为Update one BigQuery Connected Sheets data source其完整用法含别名为gog sheets (sheet) datasource (data-source,data-sources,connected-sheets) update spreadsheetId dataSourceId [flags]父命令gog sheets datasource支持sheet、data-source、data-sources、connected-sheets等多组别名命令本身接收两个必填位置参数spreadsheetId电子表格 ID兼容传入完整 URL内部会通过normalizeGoogleID提取 ID与dataSourceId数据源 ID在源码 sheets_datasource_update.go 中这两个参数分别声明为arg:的SpreadsheetID与DataSourceID两者都会先做strings.TrimSpace并校验非空。该命令是典型的“小步修改”型操作它不会重建数据源而是通过 Google Sheets API 的BatchUpdateSpreadsheetRequest提交一条UpdateDataSource请求并携带精确的字段掩码field mask只覆盖你显式传入的字段。可更新的三大类内容update 命令支持三类更新目标对应五个核心参数。结合源码 partialBigQuerySpec 的实现这三类内容为1. 替换计费执行项目Billing Projectgog sheets datasource update spreadsheetId dataSourceId --billing-project new-project对应参数--billing-project生成的字段掩码路径spec.bigQuery.projectId含义将 BigQuery 执行/计费项目切换为另一个已启用 BigQuery 计费的 Google Cloud 项目。2. 替换查询 SQLQuery Sourcegog sheets datasource update spreadsheetId dataSourceId --query SELECT ...对应参数--query生成的字段掩码路径spec.bigQuery.querySpec.rawQuery含义为查询类型的 BigQuery 数据源替换原始 SQL前提约束源码validateConnectedSheetsUpdateTarget见下节目标数据源必须是查询模式否则报错cannot apply SQL to non-query BigQuery data source。3. 替换原生表定位信息Native Tablegog sheets datasource update spreadsheetId dataSourceId \ --table-project owner-project --dataset dataset --table table对应参数--table-project、--dataset、--table三者均为可选项可单独或组合使用生成的字段掩码路径依次为spec.bigQuery.tableSpec.tableProjectId、spec.bigQuery.tableSpec.datasetId、spec.bigQuery.tableSpec.tableId含义将原生表数据源指向新的 BigQuery 表前提约束目标数据源必须是原生表模式否则报错cannot apply table fields to non-table BigQuery data source。部分更新与字段掩码原理与add整体创建不同update的核心设计是只改动显式指定的字段。这一点在源码 partialBigQuerySpec 中有清晰体现通过flagProvided(kctx, ...)判断用户是否真正传入了某个 flag只有被传入的 flag 才会写入sheets.BigQueryDataSourceSpec同时把对应的 API 字段路径追加到fields切片最终fields以逗号拼接作为UpdateDataSourceRequest.Fieldsfield mask提交。字段掩码与参数的映射关系如下表参数掩码路径field mask--billing-projectspec.bigQuery.projectId--queryspec.bigQuery.querySpec.rawQuery--table-projectspec.bigQuery.tableSpec.tableProjectId--datasetspec.bigQuery.tableSpec.datasetId--tablespec.bigQuery.tableSpec.tableId这一点被测试 TestSheetsDataSourceUpdateUsesExactFieldMasks 严格锁定。例如仅传--query时断言掩码恰为spec.bigQuery.querySpec.rawQuery且ProjectId、TableSpec必须为空仅传--billing-project时断言掩码恰为spec.bigQuery.projectIdQuerySpec、TableSpec不得被改动传入--table next --table-project owner --dataset data时掩码必须保持固定顺序spec.bigQuery.tableSpec.tableProjectId,spec.bigQuery.tableSpec.datasetId,spec.bigQuery.tableSpec.tableId传入--billing-project payer --table next时测试断言“未提供的字段必须保持不动”unsupplied fields must remain untouched。也就是说省略的字段在 API 侧不会被覆盖这是“部分更新”语义的保证也是与add命令最本质的区别。互斥与歧义输入的处理partialBigQuerySpec同时执行严格的输入约束测试 TestSheetsDataSourceUpdateRejectsInvalidInputsBeforeAuth 覆盖了全部场景--query与表相关 flag--table-project/--dataset/--table互斥同时传入报错--query and table flags are mutually exclusive五个更新参数一个都不传时报错nothing to update: pass --billing-project, --query, --table-project, --dataset, or --table任何参数传空白值都会报对应的--xxx cannot be empty--project被显式拒绝由于全局--project是--select/--pick的别名用于 JSON 输出字段选择与 BigQuery 计费项目毫无关系命令会拦截它并提示--project selects output fields; use --billing-project to change the BigQuery execution project。这一拦截在Run中通过扫描kctx.Args完成sheets_datasource_update.go避免用户误把输出选择参数当作计费项目传入。预检提交前的目标验证在真正发起写请求之前命令会调用 validateConnectedSheetsUpdateTarget 做一次只读预检调用svc.Spreadsheets.Get(spreadsheetID)且只请求最小字段集dataSources(dataSourceId,spec(bigQuery(querySpec,tableSpec)))避免拉取整份电子表格遍历返回的DataSources确认dataSourceId存在于该电子表格的 Connected Sheets 数据源中否则报错data source %s was not found in Connected Sheets校验数据源确实由 BigQuery 支撑source.Spec.BigQuery ! nil否则报错data source %s is not backed by BigQuery例如 Looker 数据源会被拒绝校验更新模式与现有模式匹配SQL 只能用于查询源表字段只能用于表源。测试 TestSheetsDataSourceUpdateRejectsWrongProviderOrSourceMode 覆盖了四类危险场景数据源缺失was not found、Looker 源not backed by BigQuery、对表源传 SQLnon-query、对查询源传表字段non-table并且断言这些场景下写请求次数必须为 0——预检失败时绝不触碰写 API。另外预检阶段的 GET 请求掩码也经过测试断言dataSources(dataSourceId,spec(bigQuery(querySpec,tableSpec)))确保这类前置查询保持轻量。提交、执行状态与错误处理通过预检后命令调用 submitConnectedSheetsWrite 提交BatchUpdateSpreadsheetRequest请求体为{ requests: [{ updateDataSource: { dataSource: { dataSourceId: dataSourceId, spec: { bigQuery: { ...: ... } } }, fields: comma-separated field mask } }] }提交环节的关键行为均有测试佐证不自动重试计费型变更写请求以googleapi.WithoutRetries(ctx)执行sheets_datasource_write.go。测试 TestSheetsDataSourceUpdateDoesNotRetryBillableMutation 模拟服务端返回 503断言写请求只尝试一次——因为 update 会立刻触发一次异步、可能产生 BigQuery 费用的执行盲目重试可能造成重复扣费。响应缺失时的保守处理若 Google 未返回UpdateDataSource应答命令不会自动重试而是报错提示provider may have updated data source %s without returning a result; inspect it before retrying并要求你先检查数据源状态sheets_datasource_update.go。应答 ID 一致性校验若返回的数据源 ID 与请求的目标不一致报错provider returned unexpected data source ...sheets_datasource_update.go。执行状态处理Google 的DataExecutionStatus会异步推进。若返回状态为FAILED命令在输出结构化 JSON 的同时以非零退出码结束通过 connectedSheetsExecutionError 组装update Connected Sheets data source: code: message错误。测试 TestSheetsDataSourceUpdateProviderFailureRetainsWrappedJSON 验证了失败场景下 JSON 输出依然完整保留dataSourceId等结构化信息。输出格式文本与 JSON默认文本模式执行状态非FAILED时输出一行Updated Connected Sheets data source dataSourceIdJSON 模式--json/-j/--machine输出包含spreadsheetId、dataSourceId、fields本次实际使用的字段掩码若响应带有执行状态则追加dataExecutionStatus包含state、lastRefreshTime、errorCode、errorMessage等。该结构适合脚本消费配合--select/--results-only可进一步裁剪输出。与list刻意不打印 SQL 不同update 的成功 JSON 只报告改动掩码而不回显查询 SQL避免敏感查询文本落入日志或脚本输出测试同样断言输出中绝不包含 provider 回显的 SQL 字符串private_query不得泄漏见 sheets_datasource_update_test.go。安全机制dry-run、readonly 与权限要求dry-run 离线预览--dry-run别名--dryrun、--noop、--preview在不发起任何认证、网络请求与写操作的前提下输出将要执行的动作。对 update 命令而言预览信息包括见 sheets_datasource_update.gospreadsheet_id、data_source_id、fields字段掩码starts_execution: true与may_incur_bigquery_charges: true提示这是一次计费型异步执行若指定了计费项目则输出billing_project若指定了 SQL 则只输出query_bytes查询字节数而绝不回显 SQL 本体。测试 TestSheetsDataSourceUpdateDryRunProtectsSQL 验证了 dry-run 输出包含sheets.datasource.update、字段掩码、query_bytes、may_incur_bigquery_charges同时断言输出中不含 SQL 内容。readonly 前置拦截--readonly会在认证与 writer 创建之前就拒绝本命令。prepareConnectedSheetsWritesheets_datasource_write.go首先检查googleapi.ReadOnly(ctx) || flags.ReadOnly命中即返回googleapi.ErrReadOnly。测试 TestSheetsDataSourceUpdateReadOnlyRejectsBeforeAuth 通过注入一个“必须不被调用”的 writer 工厂断言 readonly 模式下工厂调用次数为 0——即连 OAuth 流程都不会启动。这也意味着 update 不能被--readonly绕过。OAuth 权限与 scope 提示Google 的 Connected Sheets 文档要求 BigQuery 相关响应/操作在 Sheets 授权之外额外携带https://www.googleapis.com/auth/bigquery.readonlyscope。update 属于写操作还需要可写的 Sheets 授权。若提交时返回 scope 不足错误命令会给出可操作的重新认证提示sheets_datasource_write.gogog auth add youexample.com \ --services sheets \ --extra-scopes https://www.googleapis.com/auth/bigquery.readonly \ --force-consent若账号还覆盖其他服务应保留其原有的--services选择及任何--drive-scope、--gmail-scope配置而不是收窄为sheets。Looker 数据源则复用账号已有的 Looker 链接。更完整的数据源授权流程可参考 Connected Sheets 使用指南。完整命令行示例以下示例贯穿「预览 → 更新 → 验证」的完整工作流替换其中的尖括号占位符1. 离线预览一次 SQL 替换不触发网络与费用gog --account youexample.com sheets datasource update spreadsheetId dataSourceId \ --query SELECT region, SUM(sales) FROM dataset.orders GROUP BY region --dry-run --json2. 实际替换查询 SQLgog --account youexample.com sheets datasource update spreadsheetId dataSourceId \ --query SELECT region, SUM(sales) FROM dataset.orders GROUP BY region --json3. 仅切换计费执行项目gog --account youexample.com sheets datasource update spreadsheetId dataSourceId \ --billing-project new-billing-project --json4. 将原生表数据源指向新表可只改其中一个字段gog --account youexample.com sheets datasource update spreadsheetId dataSourceId \ --table-project analytics-prod --dataset reporting --table daily_sales_v2 --json5. 更新后轮询执行状态gog --readonly --account youexample.com sheets datasource describe \ spreadsheetId dataSourceId --jsondescribe会返回DataExecutionStatusstate为RUNNING/SUCCEEDED/FAILED待其变为SUCCEEDED后数据即生效若为FAILED输出中的errorCode/errorMessage可用于排查。Flags 完整参考以下为gog sheets datasource update的完整全局 flag 表来自命令自动生成的 schema 文档见 gog-sheets-datasource-update.mdFlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--billing-projectstringNew billing-enabled BigQuery execution project--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--datasetstringReplacement dataset for an existing native table--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children-y--force--assume-yes--yesboolSkip confirmations for destructive commands--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--querystringReplacement SQL for an existing query source--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.--tablestringReplacement native table ID--table-projectstringReplacement project owning an existing native table-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers需要注意表中--select/--pick/--project是一组输出字段选择别名与 update 的--billing-project毫无关系误传--project会被命令主动拒绝。--billing-project、--query、--table-project、--dataset、--table才是本命令的业务参数。相关资源命令文档gog sheets datasource update自动生成的 schema 文档父命令gog sheets datasource命令索引Connected Sheets 使用指南授权、增删改查、提取表的完整流程源码实现sheets_datasource_update.go、sheets_datasource_write.go、sheets_datasource.go测试用例sheets_datasource_update_test.go总而言之gog sheets datasource update是一把“手术刀”而非“大锤”精确的字段掩码、提交前的模式校验、dry-run 离线预览、readonly 前置拦截、以及计费型写请求的禁止自动重试共同保证了它在大数据源上做小改动时既安全又可审计。将它配合sheets datasource list/describe使用即可完整地完成 Connected Sheets 数据源的查看、修改与状态验证闭环。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考