跳转到主要内容
POST
创建仪表盘

限制说明

使用说明

  • dashboard_id 由调用方生成(小写的 canonical UUIDv7)。超时后用同一 ID 重试会以 DashboardIDConflict(HTTP 409)失败,而不会创建第二个仪表盘。
  • folder_id 必须是app_key 所属成员可访问的目录:其本人创建或归属其所在团队的目录及这些目录的全部子目录;账户所有者与管理员可访问全部目录之一,否则以 FolderNotFound(HTTP 404)失败。
  • 新仪表盘的 revision 从 1 开始;下次更新、移动或删除时把它作为 expected_revision 传入。
  • definition 不合法时返回 InvalidParameter(HTTP 400),错误信息按 <JSON 指针>: <原因> 逐条列出违规项。定义超过 1 MiB 或超出数量上限(如每个 tab 的 section 数、面板数、查询数或变量数),或请求体超过 2 MiB,返回 EntityTooLarge(HTTP 413);schema_version 不是 dashboard.v1 时返回 UnsupportedSchemaVersion(HTTP 422)。
  • 会记录审计日志。

授权

app_key
string
query
必填

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

请求体

application/json

创建仪表盘。ID 由调用方提供,因此超时后重试会返回 DashboardIDConflict,而不会静默创建第二个仪表盘。

dashboard_id
string
必填

由调用方生成的小写 canonical UUIDv7,作为仪表盘的永久 ID。

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

线上协议版本;只接受 dashboard.v1。

可用选项:
dashboard.v1
folder_id
integer<uint64>
必填

创建到哪个目录;该目录必须存在且 app_key 所属成员可访问,否则返回 FolderNotFound。

必填范围: x >= 1
definition
object
必填

以可移植 dashboard.v1 文档形式存储的完整仪表盘内容。未知字段、重复字段、尾随值以及超过 32 层的嵌套都会被拒绝,序列化后不得超过 1 MiB。上限:10 个 tab,每个 tab 10 个 section、30 个面板、100 条查询,每个仪表盘 100 个面板、300 条查询,20 个变量。

响应

成功

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

request_id
string
必填

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

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

已存储的仪表盘:包含标识、版本号、所在目录与完整定义。每次写入成功 revision 都会递增,下一次变更需把它作为 expected_revision 回传。