kibana-dashboards

Kibana 仪表板和 Lens 可视化

使用 Kibana 9.4+ 的仪表板和可视化 API 创建、更新和删除 Kibana 仪表板及独立 Lens 可视化。生成精简、便于比较差异的 JSON 请求体；优先使用内联面板定义，而不是库引用；并在编写指标或图表图层之前选择正确的数据集类型（数据视图还是 ES|QL）。

环境配置

此技能通过 elastic CLI 执行 Elasticsearch 操作。如果未安装 elastic CLI，请告知用户需要安装它。不要猜测凭据、直接调用 HTTP API 或尝试其他变通方法。

此技能以 HTTP 简写形式引用操作（例如，GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）。本文末尾的 操作 表格将每项简写映射到对应的 elastic CLI 命令 — 始终使用 CLI，而不是直接调用 HTTP API。

先决条件

版本要求： Kibana 9.4+（仪表板和可视化 API）。

ES|QL 的使用位置：

• 独立库图表：通过 PUT kbn:/api/visualizations/{id}，并使用 data_source.type: "esql"。
• 嵌入仪表板的 ES|QL 面板：通过 PUT kbn:/api/dashboards/{id}，在内联 vis 面板 config 中使用 data_source.type: "esql"。
• 当用户明确要求 ES|QL 时，不要使用 data_source.type: "data_view_reference" 或索引模式聚合 — 已保存的 Lens 状态必须使用基于文本的 ES|QL 数据源（textBased / esql），而不是数据视图计数操作。

流程

1. 验证 Kibana 连接。 调用 GET kbn:/api/status。如果调用失败，请停止并显示错误 — 不要猜测端点或凭据。读取 version.number，确认集群符合 9.4+ 的要求。

2. 确定任务类型。 判断用户需要的是仪表板（包含多个面板，可选时间范围）、独立 Lens 可视化（通过 ID 引用的库项目，或单独使用的可视化），还是两者都需要。确认用户是否提供了确定性的已保存对象 ID — 如果提供，请使用该 ID 进行 upsert（PUT），而不是使用会自动生成 ID 的 POST。

3. 在构建指标或图层之前选择数据集类型。

   用户意图	数据集	指标 / 轴模式
   对已保存的数据视图进行简单计数或聚合	data_source.type: "data_view_reference"，并设置 ref_id	metrics: [{ type: "primary", operation: "count" }]（或其他聚合操作）
   临时索引模式	data_source.type: "data_view_spec"，并设置 index_pattern 和 time_field	使用相同的聚合 operation 字段
   ES	QL 查询（明确要求或逻辑复杂）	data_source.type: "esql"，并设置 query

   在 ES|QL 查询中编写聚合（STATS count = COUNT()），然后按名称引用生成的列。

4. 创建或更新仪表板时构建仪表板主体。 请求主体是扁平结构 — 根级包含 title、panels 和可选的 time_range。写入时不要包装在 { data: ... } 中。必填字段：

   • title — 用户要求的确切字符串。
   • panels — 数组；用户要求空仪表板时使用 []（不要省略此键或自行编造面板）。
   • time_range — 用户指定默认时间筛选条件时，设置为 { "from": "<expr>", "to": "<expr>" }（例如 { "from": "now-7d", "to": "now" }）。提供 time_range 会在打开仪表板时保留仪表板时间筛选条件 （相当于在 UI 中启用时间恢复）。

   使用确定性 ID 执行 Upsert：

   {
     "title": "Sales Overview",
     "panels": [],
     "time_range": { "from": "now-7d", "to": "now" }
   }
   

   用户提供该 ID 时，使用上述主体调用 PUT kbn:/api/dashboards/eval-sales-overview。

   内联 ES|QL 指标面板示例（位于 panels 内）：

   {
     "type": "vis",
     "id": "total-requests",
     "grid": { "x": 0, "y": 0, "w": 12, "h": 6 },
     "config": {
       "title": "Total Requests",
       "type": "metric",
       "data_source": {
         "type": "esql",
         "query": "FROM logs* | STATS count = COUNT()"
       },
       "metrics": [{ "type": "primary", "column": "count" }]
     }
   }
   

   为了构建可移植的仪表板，优先使用内联 config 属性，而非 config.ref_id。有关面板类型、网格布局和复制工作流，请参阅 Dashboard API Reference。

5. 用户要求创建库图表时，构建独立的 Lens 可视化。 使用 Visualizations API。提供 ID 时，使用 PUT kbn:/api/visualizations/{id} 执行 Upsert；否则使用 POST kbn:/api/visualizations，并报告响应中生成的 ID。

   ES|QL 指标（日志总数）：

   {
     "type": "metric",
     "title": "Total Requests",
     "data_source": {
       "type": "esql",
       "query": "FROM logs* | STATS count = COUNT()"
     },
     "metrics": [{ "type": "primary", "column": "count" }]
   }
   

   需要使用该 ID 时，调用 PUT kbn:/api/visualizations/eval-total-requests。该 API 会持久化一个 Lens 已保存对象， 其数据源状态使用 ES|QL（textBased / esql），而非索引模式聚合。

   有关 xy、仪表盘、热力图和其他图表架构，请参阅 Lens API Reference 和 Chart Types Reference。

6. 执行并确认。 使用 PUT kbn:/api/dashboards/{id} 或 PUT kbn:/api/visualizations/{id} 执行写入 （未提供 ID 时使用 POST）。通过 GET kbn:/api/dashboards/{id} 或 GET kbn:/api/visualizations/{id} 确认。向用户报告 ID 和标题 — 未成功回读前，不要声称操作成功。

7. 按需列出、导出或删除。 调用 GET kbn:/api/dashboards 或 GET kbn:/api/visualizations 以 查找现有对象。调用 DELETE kbn:/api/dashboards/{id} 或 DELETE kbn:/api/visualizations/{id} 删除对象。 批量导出或导入已保存对象时，调用 POST kbn:/api/saved_objects/_export 或 POST kbn:/api/saved_objects/_import。

仪表板网格

仪表板使用 48 列网格。在 16:9 屏幕上，首屏大约可容纳 20–24 行 — 目标是在该区域内放置 8–12 个面板。

宽度	列数	高度（行）	用途
全宽	48	14–16	宽幅时间序列、表格
半宽	24	10–12	主要图表
四分之一宽	12	5–6	KPI 指标
六分之一宽	8	4–5	密集指标行

网格排布： 堆叠行时，将下一个面板的 y 设置为前一个面板的 y + h。共享同一行的面板应使用相同的 h。不要使用 Markdown 面板作为仪表板标题 — 请改用描述性的图表标题。

ES|QL 模式

时间序列分桶（仪表板时间选择器会注入 ?_tstart / ?_tend）：

FROM logs*
| WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart
| STATS count = COUNT() BY BUCKET(@timestamp, 75, ?_tstart, ?_tend)

对于时间序列 xy 图表，将 x 轴的 "scale": "temporal"。有关坐标轴和图层的详细信息，请参阅 Chart Types Reference。

静态参考值 — 在查询中使用 EVAL，然后引用该列：

FROM logs* | STATS count = COUNT() | EVAL goal = 15000

示例

JSON 定义示例位于 assets/ 下：demo-dashboard.json、dashboard-with-visualizations.json、 metric-esql.json、bar-chart-esql.json、line-chart-timeseries.json。

指南

1. 用户提供 id 和标题时，必须完全匹配，不要替换为自动生成的 id。
2. 保留空面板——用户要求 panels: [] 时，发送空数组；不要添加占位面板。
3. 按要求使用 ES|QL——使用 data_source.type: "esql" 和列引用；切勿在数据视图上使用 operation: "count" 来满足 ES|QL 请求。
4. 保持载荷精简——省略可推导的默认值，让 API 注入样式和元数据。
5. 确认写入结果——创建或更新后，始终使用 GET 读回数据。
6. 生成复杂图表前先阅读参考资料——数据视图和 ES|QL 的指标图与 XY 图架构不同；生成分区图或表格图前，请查阅图表类型参考。

常见问题

错误	可能原因	修复方法
PUT 后 GET 返回 404	id 或空间错误	确认 id，然后重试 GET kbn:/api/dashboards/{id}
400 校验错误	ES|QL 列不匹配	使 metrics[].column / 图层 column 与查询中的 STATS 别名一致
ES|QL 面板保存为数据视图	数据集类型错误	使用 data_source.type: "esql"，不要使用 data_view_reference
空仪表板缺少时间筛选器	未提供 time_range	需要默认时间范围时，添加 { "from": "now-7d", "to": "now" }
XY 图表失败	缺少图层 data_source	将 data_source 放在每个图层内，而不只是根级别

操作

从 CLI v0.3.0 起，Dashboards 和 Visualizations API 已提供专用的 elastic kb dashboards 和 elastic kb visualizations 命令，可按 id 列出、读取、更新和删除对象。create-*-redirect 命令目前尚不接受请求正文，因此要写入新对象，请提供 id 并使用 update-*-redirect（PUT） 命令，通过 --input-file 传入 JSON 正文。若要一次编写多个对象，请构建 saved-object NDJSON 文件，并使用 post-saved-objects-import 导入（使用 post-saved-objects-export 读回）。

HTTP API（简写）	elastic CLI 命令
GET kbn:/api/status	elastic kb system get-status
POST kbn:/api/saved_objects/_import	elastic kb saved-objects post-saved-objects-import --file '<path.ndjson>' --overwrite
POST kbn:/api/saved_objects/_export	elastic kb saved-objects post-saved-objects-export --objects '[{"type":"<type>","id":"<id>"}]'
GET kbn:/api/dashboards	elastic kb dashboards get-dashboards-redirect
GET kbn:/api/dashboards/{id}	elastic kb dashboards get-dashboard-redirect --id '<id>'
PUT kbn:/api/dashboards/{id}	elastic kb dashboards update-dashboard-redirect --id '<id>' --input-file '<path.json>'
DELETE kbn:/api/dashboards/{id}	elastic kb dashboards delete-dashboard-redirect --id '<id>'
POST kbn:/api/dashboards (no id)	create-dashboard-redirect 目前不接受请求正文 — 请提供 id 并使用 update-dashboard-redirect，或通过 post-saved-objects-import 编写（类型为 dashboard）
GET kbn:/api/visualizations	elastic kb visualizations get-visualizations-redirect
GET kbn:/api/visualizations/{id}	elastic kb visualizations get-visualization-redirect --id '<id>'
PUT kbn:/api/visualizations/{id}	elastic kb visualizations update-visualization-redirect --id '<id>' --input-file '<path.json>'
DELETE kbn:/api/visualizations/{id}	elastic kb visualizations delete-visualization-redirect --id '<id>'
POST kbn:/api/visualizations (no id)	create-visualization-redirect 目前不接受请求正文 — 请提供 id 并使用 update-visualization-redirect，或通过 post-saved-objects-import 编写（类型为 lens）