跳转到主要内容
POST
运行仪表盘面板

限制说明

使用说明

  • 对已存仪表盘当前版本的单个面板,把其全部查询发往对应数据源执行。即使所有查询都失败,调用仍返回 HTTP 200,请查看 run_state 以及各 ref 的 state、error。
  • 省略 revision(或传 0)表示按当前版本运行。传入它时,若仪表盘已被修改,调用以 DashboardRevisionConflict(HTTP 409)失败,而不是返回基于过期定义的数据。
  • run_state 汇总各 ref:全部成功为 success,至少一个成功且至少一个未成功为 partial,否则为 cancelled、incompatible 或 error。查询已执行但结果与面板可视化不匹配(例如配置的值字段缺失或不是数值)时,该 ref 为 incompatible。
  • 每个 ref 的 execution 随数据源而异且原样透传;child_request_id 标识底层数据源调用。文本面板不能运行(HTTP 400),panel_id 不存在时返回 TargetNotFound(HTTP 404)。
  • max_data_points 默认 100,取值 2~5000。单个面板内最多同时运行 6 个查询。响应超过 8 MiB 时以 EntityTooLarge(HTTP 413)拒绝,而不会截断。整个调用有 35 秒的总时限,超时返回 RuntimeTimeout(HTTP 504)。

授权

app_key
string
query
必填

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

请求体

application/json

执行已存仪表盘的某个面板。省略 revision(或传 0)表示按当前版本运行;传入它可让过期调用被拒绝。文本面板不能运行。

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_id
string
必填

要执行的面板 ID。必须属于该仪表盘,否则返回 TargetNotFound(HTTP 404)。

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 安全整数上限。

revision
integer<uint64>

版本护栏。设置(非 0)时必须等于仪表盘当前版本号,否则以 DashboardRevisionConflict(HTTP 409)失败。省略或传 0 表示不校验。

variables
object

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

max_data_points
integer | null

range 查询每条序列的目标最大点数,服务端据此推算查询步长。取值 2~5000;省略或传 null 时默认 100。

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

响应

成功

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

request_id
string
必填

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

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

面板执行结果。即使所有查询都失败也返回 HTTP 200,请查看 run_state 以及各 ref 的 state、error。响应超过 8 MiB 时以 EntityTooLarge(HTTP 413)拒绝,而不会截断。