奇链 奇链
← 文章 / 数据与数据库
signoz 10天前 · 2026-10-25 06:02:31 · 15 阅读

仪表盘 V2 API——架构、端点与 PATCH 更新

SigNoz Dashboards 基于重新设计且兼容 Perses 的 schema 运行。现有的看板、查询、变量和面板会自动迁移至新 schema。新架构让看板更易于查找、组织和规模化管控。

  • 看板更易查找和管理：支持键值标签、个人置顶、共享已保存视图及快速克隆，并定义了 JSON/Terraform schema，支持直接编辑、部分更新（节省 token）以及可靠的 AI 驱动变更。
  • 面板表达力更强：新增样式控制（填充模式、线条插值、断开线条、显示数据点）以及 PNG/SVG 导出功能，便于在报告和事故复盘文档中分享。

你需要了解的事项

  • 当 SigNoz 启动时，现有看板会自动迁移至 V2 schema。
  • 通过 UI 使用的看板无需任何操作即可正常工作。
  • 如果你有通过 Terraform 管理或脚本直接调用 Dashboards API 的看板，请将其迁移至 V2 schema 和端点。参见 v0.135.0 升级指南 了解迁移路径。
V1 看板 API 已停用

V1 看板端点（/api/v1/dashboards 及其子路由）已永久禁用。所有调用将返回 HTTP 501 Not Implemented，错误代码为 dashboard_deprecated，并附带指明 V2 替代端点的提示信息。无过渡期，因此 501 可能是你的集成、服务账号或自动化流程收到的第一个异常信号。请将所有直接 API 调用迁移至下方的 V2 端点。公共分享路由（/api/v1/dashboards/{id}/public 和 /api/v1/public/dashboards/{id}）不受影响，仍可正常工作。

如果你有直接使用 Dashboards API 的脚本

将这些脚本迁移至 V2 Dashboards API。你可以参考本指南下方的示例。

V2 规范严格校验

V2 schema 执行严格校验。请更新 API 和 dashboard-as-code（Terraform）客户端以符合以下规则：

  • 省略枚举字段没问题，但发送空字符串不行。 如果省略某个枚举字段，它会取默认值；但如果显式发送 ""，请求会被拒绝，返回 400 Bad Request 和错误码 dashboard_invalid_input。这会让那些序列化所有字段（包括未设置的字段）的客户端出错。受影响的字段包括：timePreference、legendPosition、legendMode、thresholdFormat、comparisonOperator、lineInterpolation、lineStyle、fillMode、precisionOption 以及 listVariableSort。
  • 布局必须符合网格规则。 关于边界、重叠规则及错误信息，请参阅仪表板布局约束。
Warning

时序 chartAppearance.spanGaps 字段会受到校验。当 fillOnlyBelow 为 true 时，fillLessThan 为必填项，且必须为正持续时间。fillLessThan 支持秒（s）、分钟（m）、小时（h）、天（d）和周（w）等单位，也支持复合值（例如 5m、1d、1w、1h30m）。任何带有 fillOnlyBelow: true 但缺失、为空或非正数的 fillLessThan 的仪表板载荷，在保存或加载时都会校验失败。请更新这些面板或 API/Terraform 载荷，使用有效的持续时间。在 UI 中，这两个字段对应当数据缺失时选项下的断开长间隙，以及其当间隙长于以下时间时断开输入框。详见数据缺失时。

GET 响应中的零值与可空字段

V2 仪表板 API 会忠实往返传输零值字段。在脚本、SDK 或生成的客户端中解析 GET 响应前，请留意以下事项：

  • 阈值为精确的 0 是被接受的。 面板可以设置 0 阈值，API 不会拒绝它。
  • GET 响应中始终包含零值字段。Query 对象总会带有 disabled: false 和 legend: ""，显式设置的空数组（group-by、排序、选中字段、聚合、函数及函数参数）往返后依然是 []，而从未设置过的数组则不会出现。在 spec 层面，image、duration、refreshInterval 和显示描述在未设置时序列化为 ""；文本变量的 constant 序列化为 false，列表变量的 customAllValue 和 capturingRegexp 序列化为 ""。
  • 部分字段可为 null。仪表盘的 datasources 映射、仪表盘和面板级别的 links 数组，以及若干查询数组字段都可能返回 null。生成的客户端会将其类型定义为 Type[] | null（或可空的 map），因此处理 [] 的同时也要处理 null。
  • 如果你的集成逻辑是通过判断 key 缺失来检测"未设置"，请改为直接检查字段值，因为这些 key 现在始终存在。

告警规则使用相同的底层查询格式，因此其 GET 响应也会有同样的 disabled、legend 和空数组行为。API Reference 是权威的 schema 文档。注意 DashboardLink schema 组件已更名为 DashboardtypesLink（字段结构不变），如有工具或生成的客户端按名称引用它，请及时更新。

如果你用 Terraform 同步仪表盘

与本次 SigNoz 版本对应的 Terraform Provider 发布版会附带迁移脚本，用于把你的资源迁移到新 schema。你可以先运行脚本，然后再调整资源、定义所需的变量。详见 Terraform provider 指南。

Dashboards V2 API 指南

Dashboards API 现在运行在严格校验的 schema 之上，遵循 Perses 的 schema 规范。

仪表盘由多个 layout 组成，每个 layout 中排列着若干 panel。变量依旧可以用来在各个 panel 之间筛选数据。

仪表盘还带有一组 key: value 形式的标签，便于将其分组管理，也提供了按键或值快速查询的便捷方式。

完整 Schema 可以在新的 Create Dashboard API 的请求体中查看。

仪表盘 Schema 概览

Copy
{
    "tags": [
        {
            "key": "string",
            "value": "string"
        }
    ],
    "spec": {
        "display": {
            "name": "string",
            "description": "string"
        },
        "layouts": [],
        "panels": {
            "panel-name": { /* panel details */ }
        },
        "variables": []
    }
}

spec 的必填字段

从 SigNoz v0.136.0 开始，每个仪表盘的 spec 必须包含 variables、panels 和 layouts，且均不能为 null。如果仪表盘没有某类内容，需传入空集合：

  • variables：数组。无变量时使用 []。
  • panels：对象。无面板时使用 {}。
  • layouts：数组。无布局时使用 []。

最小的合法 spec 如下：

Copy
{
    "variables": [],
    "panels": {},
    "layouts": []
}

该规则适用于创建（POST）和更新（PUT）请求体，以及经 PATCH 处理后的仪表盘。任何删除上述字段或将其设为 null 的 patch 都会被拒绝。违反规则的请求将返回 400 Bad Request，错误码为 dashboard_invalid_input。SigNoz 按顺序检查字段，并报告第一个缺失项：

Copy
spec.variables: is required and must not be null; use [] for a dashboard with no variables
spec.panels: is required and must not be null; use {} for a dashboard with no panels
spec.layouts: is required and must not be null; use [] for a dashboard with no layouts

现有仪表盘无需手动修改。升级至 SigNoz v0.136.0 或更高版本时，一次性数据库迁移会将缺失或为 null 的 spec.variables、spec.panels 或 spec.layouts 替换为空集合。

每个面板都需要提供 spec.queries 字段，且该字段不能为 null。文本面板（Text panel）必须使用 []，此支持从 SigNoz v0.142.0 版本开始引入。其他所有类型的面板都恰好需要一个查询。

仪表盘 API

仪表盘的列表和 CRUD（创建、读取、更新、删除）操作现已全部提供 V2 版本接口：

Copy 
GET    /api/v2/dashboards          -- 获取仪表盘列表
POST   /api/v2/dashboards          -- 创建仪表盘
GET    /api/v2/dashboards/{id}     -- 获取仪表盘详情
PUT    /api/v2/dashboards/{id}     -- 更新仪表盘
DELETE /api/v2/dashboards/{id}     -- 删除仪表盘

仪表盘的加锁与解锁操作拥有新的端点：

Copy 
PUT    /api/v2/dashboards/{id}/lock  -- 锁定仪表盘
DELETE /api/v2/dashboards/{id}/lock  -- 解锁仪表盘

从 V1 仪表盘 API 迁移

V1 仪表盘端点已正式弃用。所有请求现在都会返回 HTTP 501 Not Implemented 状态码，并附带错误码 dashboard_deprecated 及一条指明对应 V2 替代接口的提示信息，便于集成方通过响应体自行诊断问题。请将每个调用迁移到对应的 V2 接口：

V1 端点（现为 501）V2 端点操作
GET /api/v1/dashboardsGET /api/v2/dashboards获取仪表盘列表
POST /api/v1/dashboardsPOST /api/v2/dashboards创建仪表盘
GET /api/v1/dashboards/{id}GET /api/v2/dashboards/{id}获取仪表盘
PUT /api/v1/dashboards/{id}PUT /api/v2/dashboards/{id} 或 PATCH /api/v2/dashboards/{id}更新仪表盘（PUT 整体替换仪表盘配置，PATCH 执行局部更新）
DELETE /api/v1/dashboards/{id}DELETE /api/v2/dashboards/{id}删除仪表盘
PUT /api/v1/dashboards/{id}/lockPUT /api/v2/dashboards/{id}/lock（锁定）、DELETE /api/v2/dashboards/{id}/lock（解锁）锁定或解锁仪表盘

请求体的结构也变了：从 V1 的扁平 JSON 变成上文所述的 Perses spec 树。自托管用户升级到 v0.135.0 时，请参照升级指南操作，

原始来源： signoz

评论 (0)