Kibana Saved Objects API 技能

通过 REST API 管理 Kibana Saved Objects，包括仪表板（dashboard）、Lens 可视化及其他 Kibana 实体。

基础 URL

http:///api/saved_objects

Omni-Monitor 示例：http://192.168.99.43/api/saved_objects

必需请求头：kbn-xsrf: true

核心端点

1. 创建 Saved Object

POST /api/saved_objects/

请求体：

{
  "attributes": {
    "title": "我的仪表板",
    "description": "..."
  },
  "id": "可选的自定义 ID",
  "references": [{"id": "...", "name": "...", "type": "index-pattern"}]
}

2. 获取 Saved Object

GET /api/saved_objects//

3. 更新 Saved Object

PUT /api/saved_objects//

请求体：

{
  "attributes": {
    "title": "已更新的标题"
  },
  "references": [...]
}

4. 删除 Saved Object

DELETE /api/saved_objects//

5. 批量获取（Bulk Get）

POST /api/saved_objects/_bulk_get

请求体：

{
  "objects": [
    {"type": "dashboard", "id": "abc123"},
    {"type": "lens", "id": "def456"}
  ]
}

6. 批量创建（Bulk Create）

POST /api/saved_objects/_bulk_create

请求体：

{
  "objects": [
    {"type": "dashboard", "id": "...", "attributes": {...}},
    {"type": "lens", "id": "...", "attributes": {...}}
  ]
}

7. 导出 Saved Objects

POST /api/saved_objects/_export

请求体：

{
  "objects": [
    {"type": "dashboard", "id": "abc123"},
    {"type": "lens", "id": "def456"}
  ]
}

返回值： Saved Objects 的 NDJSON 流

8. 导入 Saved Objects

POST /api/saved_objects/_import?overwrite=true

Content-Type：multipart/form-data
表单字段：file = NDJSON 文件

9. 查询（Find / Search）Saved Objects

POST /api/saved_objects/_find

请求体：

{
  "type": "dashboard",
  "search": "标题关键词",
  "searchFields": ["title", "description"],
  "page": 1,
  "perPage": 20
}

常见对象类型

引用系统（References System）

引用（References）用于关联不同对象。例如，一个仪表板面板（Lens）会引用：

1. 其所使用的 index-pattern（即数据视图）
2. 其所属的父级仪表板（如有）

引用格式示例：

{
  "id": "b58d25c5-c05c-47be-a6cb-4073ef478a8f",
  "name": "indexpattern-datasource-layer-aca264a7-bf68-47b3-af63-db1e67fe0646",
  "type": "index-pattern"
}

带引用创建对象示例：

{
  "type": "lens",
  "attributes": {
    "title": "CPU 使用率",
    "state": {
      "datasourceStates": {...},
      "visualization": {...}
    }
  },
  "references": [
    {"id": "b58d25c5-c05c-47be-a6cb-4073ef478a8f", "name": "indexpattern-datasource-layer-xxx", "type": "index-pattern"}
  ]
}

仪表板结构（Dashboard Structure）

仪表板 attributes 字段示例：

{
  "title": "仪表板名称",
  "description": "可选描述",
  "panelsJSON": "[{"type":"lens","gridData":{...},"embeddableConfig":{...}}]",
  "optionsJSON": "{"useMargins":true,"syncColors":false,"hidePanelTitles":false}",
  "timeRestore": true,
  "timeTo": "now",
  "timeFrom": "now-24h",
  "refreshInterval": {
    "pause": false,
    "value": 300000
  }
}

Lens 对象结构

Lens 是 Kibana 的新一代可视化工具。其关键结构如下：

{
  "type": "lens",
  "attributes": {
    "title": "指标标题",
    "state": {
      "datasourceStates": {
        "formBased": {
          "layers": {
            "": {
              "columns": {
                "": {
                  "label": "指标标签",
                  "dataType": "number",
                  "operationType": "count|average|sum|max|min",
                  "sourceField": "field.name",
                  "isBucketed": false,
                  "scale": "ratio"
                }
              },
              "columnOrder": [""],
              "incompleteColumns": {}
            }
          }
        }
      },
      "visualization": {
        "layerId": "",
        "layerType": "data",
        "metricAccessor": ""
      }
    }
  },
  "references": [
    {"id": "", "name": "indexpattern-datasource-layer-", "type": "index-pattern"}
  ]
}

lnsMetric（单指标）结构：

{
  "layerId": "...",
  "layerType": "data",
  "metricAccessor": ""
}

lnsXY（折线图/柱状图/面积图）结构：

{
  "layerId": "...",
  "layerType": "data",
  "layers": [{
    "layerId": "...",
    "accessors": [""],
    "position": "top",
    "seriesType": "bar|line|area",
    "showGridlines": false,
    "xAccessor": ""
  }]
}

重要规则

1. 切勿将 __records___ 用作 sourceField → 否则将导致 “Field not found” 错误
2. 文本字段在聚合时必须使用 .keyword 后缀（例如：host.keyword）
3. 引用名称必须符合规范格式 → 必须为 indexpattern-datasource-layer-
4. Lens 中的 layerId 和 accessor UUID 在每个可视化中必须唯一

NDJSON 导入/导出格式

导出结果示例：

{"attributes":{"title":"Dash 1"...},"id":"abc","type":"dashboard","references":[...]}
{"attributes":{"title":"Lens 1"...},"id":"def","type":"lens","references":[...]}

导入要求：使用相同格式；添加参数 overwrite=true 将覆盖已有对象。

脚本

参见

• kibana-data-views — 管理数据视图（index patterns）
• kibana-lens-builder — 为监控场景生成 Lens 可视化

故障排查

“Cannot read properties of undefined (reading 'indexpattern')”

原因：仪表板或 Lens 引用了不存在的数据视图（data view）。

解决方法：

1. 列出全部数据视图：GET /api/data_views
2. 确认所引用的数据视图 ID 是否存在
3. 如缺失，使用 kibana-data-views 重建对应数据视图

“Field not found” 错误

原因：对文本字段执行聚合操作时未使用 .keyword 后缀。

解决方法：应使用 host.keyword 而非 host，使用 metric_type.keyword 而非 metric_type

Saved Object 损坏（GET 返回 404，但在列表中可见）

解决方法：

1. 删除损坏的对象：DELETE /api/saved_objects//
2. 使用正确数据重新创建该对象