跳转到主要内容
POST
解析面板查询

限制说明

使用说明

  • 用于在运行之前展示面板将命中哪个数据源、使用什么表达式。不会执行任何查询。
  • panel_ids 接受 1~100 个唯一 ID,按请求顺序返回。面板不在该仪表盘中时,返回 state: "error"、原因 panel_missing,而不会使整个调用失败;文本面板返回 state: "error"、原因 invalid_request。
  • 面板的全部查询解析成功时 state 为 success,只有部分成功为 partial,全部失败为 error。queries 列出解析成功的查询;error 只报告第一个失败。
  • 内置时间变量(如步长、时间范围)根据 time 和 max_data_points 渲染;preserve_builtin_variables 为 true 时原样保留,供调用方用自己的窗口渲染。用户变量始终会被解析。
  • 面板查询只能绑定到 Prometheus、MySQL、Loki 数据源。整个调用有 35 秒的总时限,超时返回 RuntimeTimeout(HTTP 504)。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

只解析所选面板的查询而不执行,便于客户端预览数据源绑定与变量替换结果。

dashboard_id
string
必填

仪表盘的 canonical UUIDv7。

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
panel_ids
string[]
必填

要解析的面板,1~100 个唯一 ID。面板不存在时产生 error 分支,而不会让调用失败。

Required array length: 1 - 100 elements
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
time
object
必填

绝对求值窗口。两个边界都是 Unix 毫秒时间戳,from_ms 必须小于 to_ms,且都不得超过 JavaScript 安全整数上限。

variables
object

按变量名索引的选择,最多 20 项。未给出的变量回退到存储的默认值;出现仪表盘未定义的变量名时,调用以 HTTP 400 失败。

max_data_points
integer | null

每条序列的目标最大点数,用于计算步长并渲染内置时间变量。取值 2~5000;省略或传 null 时默认 100。

必填范围: 2 <= x <= 5000
preserve_builtin_variables
boolean

在解析结果中逐字保留内置时间变量,供调用方按自己的执行窗口渲染;用户变量照常解析。

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse。

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

所请求面板的已解析查询,以及解析时采用的生效变量选择。不会执行任何查询。