twells89/sigma-source-parameter-repair

# sigma-source-parameter-repair 在替换数据源后，检测并修复 [Sigma](https://www.sigmacomputing.com/) 工作簿中损坏的**源参数**（source parameters）。 如果你使用模板数据模型（data model）和模板工作簿（workbook），并为每个新团队、租户（tenant）或环境克隆它们，你可能遇到过这个问题：当你将新工作簿替换到新数据模型上时，所有源参数会立刻失效。此工具可以一次性修复它们。 无依赖项 — 仅需 Python 3.9+ 标准库。 ## 问题所在 工作簿控件可以驱动定义在数据模型内部的控件。这种绑定被称为*源参数*（source parameter），在工作簿规格（spec）中它看起来像这样： ``` - kind: control controlId: RegionControl # the workbook-side control id: aBcDeFgHiJcon filters: - source: { kind: table, elementId: KLm0nOpQrS } columnId: TuVwXyZ012 parameters: # <-- the source parameter - kind: data-model dataModelId: 11111111-1111-1111-1111-111111111111 controlId: Store-Region # the control inside the data model ``` `swapSources` 接受 `columnMapping` 和 `metricMapping`，仅此而已。这里没有参数映射。因此，当你替换工作簿的源时，Sigma 会重写每个元素的 `source.dataModelId`，但会让每个 `parameters[].dataModelId` 仍然指向**旧**的数据模型。此时，每个源参数都会引用一个工作簿不再从中读取数据的模型，因此 Sigma 会将其标记为无效。 修复方法并不复杂：重写那个字段即可。棘手的是，一个真实的模板工作簿有几十个分布在几十个元素上的参数，而 Sigma UI 要求你逐一访问。 ## 为什么自动化是安全的 克隆数据模型会**逐字保留其控件 ID**。除了标识字段外，模板模型及其副本是完全相同的，一直到每个控件的 `controlId` 都是如此。因此，修复过程只是直接的 ID 重写，而不是模糊名称匹配，并且该工具可以验证其选择：在重写绑定之前，它会确认目标数据模型确实定义了具有该 ID 的控件。 如果无法确认这一点，它会拒绝猜测。参见[解析规则](#resolution-rules)。 ## 安装 ``` git clone https://github.com/twells89/sigma-source-parameter-repair.git cd sigma-source-parameter-repair ``` 就这样。你也可以选择将其添加到你的 `PATH` 中： ``` chmod +x sigma_source_params.py ln -s "$PWD/sigma_source_params.py" ~/.local/bin/sigma-source-params ``` ## 凭证 在 Sigma 的 **Administration → APIs and Tokens** 下创建 API 凭证，然后导出它们。`SIGMA_BASE_URL` 是你的云和区域的 **API host**，而不是你的应用 URL — 你可以在 **Administration → Developer Access** 下，或者在 [Sigma 的区域支持表格](https://help.sigmacomputing.com/docs/region-warehouse-and-feature-support)中查找它。 ``` export SIGMA_BASE_URL="https://aws-api.sigmacomputing.com" # adjust to your region export SIGMA_CLIENT_ID="..." export SIGMA_CLIENT_SECRET="..." ``` 凭证所有者需要对工作簿拥有 **Can edit** 访问权限，并且其账户类型需要具有*创建、编辑和发布工作簿*（Create, edit, and publish workbooks）的权限。 ## 使用方法 从工作簿的 URL 中获取工作簿 ID — 可以是 UUID，也可以是短 URL ID。 ### 检查 在不更改任何内容的情况下报告工作簿的状态。如果任何绑定需要处理，它会以代码 `1` 退出，因此可以用作流水线闸门。 ``` python3 sigma_source_params.py check WORKBOOK_ID ``` ``` workbook : Regional Template (version 3) reads from: 22222222-2222-2222-2222-222222222222 source parameters: 3 [REPAIR ] 'City' (element aBcDeFgHiJcon) data model control: Store-City 11111111-1111-1111-1111-111111111111 -> 22222222-2222-2222-2222-222222222222 live source defines control 'Store-City' ... 3 source parameter(s) need attention. ``` 添加 `--json` 以获取机器可读的输出。 ### 修复 默认为预运行（dry run）— 它会准确打印出将要进行的更改，但不会触动任何实际内容： ``` python3 sigma_source_params.py repair WORKBOOK_ID ``` 写入更改： ``` python3 sigma_source_params.py repair WORKBOOK_ID --apply ``` `--apply` 会创建一个**新的工作簿版本**。以前的版本在 Sigma 的版本历史记录中仍然可用，因此该更改是可还原的。 写入后，该工具会重新读取工作簿并报告仍有多少绑定需要处理，而不是假设写入已成功。 ## 解析规则 对于每个 `dataModelId` 不属于工作簿有效数据模型源之一的源参数，工具会选择一个目标： | 情况 | 结果 | | --- | --- | | 已经指向有效的源 | `ok` — 保持不变 | | 恰好有一个有效源定义了具有该 ID 的控件 | `REPAIR` — 重写为该源 | | 多个有效源定义了该控件 ID | `AMBIGUOUS` — 保持不变，并报告 | | 没有有效源定义该控件 ID | `NO MATCH` — 保持不变，并报告 | 后两种情况是刻意为之。如果在新的数据模型中控件被重命名或删除，正确的目标需要基于意图进行主观判断，而静默地将其重新绑定到看似合理的目标上，还不如明确指出问题。`--apply` 会修复它能确认的部分，保留其余部分不变，并以非零代码退出，让你知道还有剩余工作。 修复是幂等的 — 运行两次是空操作（no-op）。 ## 退出代码 | 代码 | 含义 | | --- | --- | | `0` | 无需关注任何内容（或预运行已完成） | | `1` | 发现过期绑定，或部分绑定无法自动解析 | | `2` | 缺少凭证或凭证无效 | | `3` | Sigma API 返回错误 | ## 将其用作发布闸门 基于模板进行配置的持久模式是将修复过程纳入流水线，而不是依靠人工记忆： ``` # 1. clone 模板 data model # 2. clone 模板 workbook # 3. 将新 workbook 替换到新 data model 上 # 4. 修复步骤 3 无法保留的 source parameters python3 sigma_source_params.py repair "$NEW_WORKBOOK_ID" --apply # 5. 如果仍有任何未解决的问题，则使 rollout 失败 python3 sigma_source_params.py check "$NEW_WORKBOOK_ID" ``` ## 一个有用的副作用 Sigma 的写入路径会验证源参数。`POST /v2/workbooks/spec` 和 `PUT /v2/workbooks/{id}/spec` 会拒绝过期的绑定，并返回一条消息，准确指明出问题的项： ``` { "message": "Invalid parameter on control: aBcDeFgHiJcon targeting data model: 11111111-1111-1111-1111-111111111111, controlId: Store-City.", "code": "invalid_request" } ``` 因此，能够顺利写入的 spec 没有损坏的源参数。请注意，`GET` **不会**进行验证 — 它会正常返回过期的绑定 — 因此仅仅读回数据并不能证明任何问题。只有写入路径才是真正的检查。 ## 限制 - 仅处理 `kind: data-model` 参数。其他类型的参数将被忽略。 - 工作簿规格（spec）端点是 Sigma 的 **beta** API，可能会发生更改。 - 该工具在 API 层验证修复。它无法替你点击仪表板 — 你需要自行打开工作簿以确认控件行为符合预期。 ## 延伸阅读 - [工作原理](docs/how-it-works.md) — 该工具背后的 spec 结构和 API 契约 - [以代码形式管理工作簿](https://help.sigmacomputing.com/docs/manage-workbooks-as-code) - [Sigma REST API 参考](https://help.sigmacomputing.com/reference) ## 许可证 [Apache-2.0](LICENSE) 非官方 Sigma Computing 产品。

标签：BI工具, Python, SOC Prime, 动态分析, 开发工具, 数字取证, 数据治理, 无后门, 自动化脚本