Kibana 仪表板 API：为每种面板类型提供稳定的 API 规范，正式发布前已经过 50 多个团队测试

Kibana 仪表板和可视化 API 在 Elastic 9.5 中已可用于生产环境，所有订阅级别均可使用，并提供完全向后兼容性。以 JSON 格式定义仪表板，将其提交到 Git，然后使用持续集成和持续部署 (CI/CD) 管道、Terraform 或您现有的任何工具，将其部署到不同环境。在 9.4 技术预览期间，50 多个团队测试了该 API，其中一些团队已将其用于生产环境。9.5 版本还新增了用于标签的终端（技术预览阶段）；Markdown 和链接面板终端现已在 Elastic Cloud Serverless 中提供，并将在 9.6 中推出。

Kibana 仪表板 API 中的向后兼容性意味着什么

在技术预览期间，API 结构可能会随版本发生变化。[1]现在已不再如此。正式发布 (GA) 意味着：

• 完全向后兼容。新字段和面板类型将陆续添加，但现有字段和行为保持不变。未来如需引入任何破坏性变更，都会经过慎重评估，并且只会在新的 Elastic Stack 主版本中引入。

• 可用于生产环境，并提供全面支持。该 API 享有 Elastic 提供的全面支持保障。您可以放心地在生产环境中使用该 API，进行自动化部署、跨环境发布以及以编程方式管理仪表板。

Kibana 新增用于标签、Markdown 和链接面板的 API 终端

Elastic 9.5 还新增了一个用于标签的独立终端，让您可以对仪表板进行分类和筛选。现在，您可以通过专用 CRUD 终端以编程方式管理这些标签，从而更轻松地跨环境大规模组织仪表板。

新的 Markdown 和链接面板终端现已在 Serverless 中提供，并将在下一个 Elastic Stack 版本 (9.6) 中推出。

Kibana 仪表板 API 支持哪些面板类型？

仪表板 API 支持 9.5 中的所有按值面板（即直接在仪表板中定义的面板，而非保存以供重复使用的库面板）。每种受支持的面板类型都有一个类型化且经过验证的架构。

如何以代码形式管理 Kibana 仪表板

仪表板 API 支持一套完整的以代码形式管理仪表板的工作流：将仪表板导出为简洁、可进行差异比较的 JSON，将其提交到 Git 并作为唯一可信来源，在拉取请求中审查更改，然后将同一定义部署到开发、预发布和生产环境。一旦以代码形式管理仪表板，就应将 Git 作为唯一可信来源：下次部署会覆盖直接在 UI 中所做的更改。

在空间、集群或阶段之间迁移仪表板时，主要挑战在于仪表板会按 ID 引用 Data view、库可视化等对象。由于这些 ID 是自动生成的，且不同环境中的 ID 各不相同，因此从一个环境导出的仪表板可能会引用另一个环境中不存在的对象。有三种方法可以处理这个问题，以下按自动化程度从高到低列出：

• 使用 Terraform。Elastic Stack Terraform 提供程序会跟踪每项资源，并自动映射各环境中的 ID，因此当您将仪表板从开发环境发布到生产环境时，引用可保持一致。

• 定义按值的 Elasticsearch 查询语言 (ES|QL) 面板。构建面板时，可移植性最高的方法是在仪表板中直接使用 ES|QL 定义其可视化。ES|QL 查询会从查询中指定的索引读取数据，因此面板不会包含对 Data view 或库对象的外部引用。这样便可获得一个完全自包含、可移植的仪表板。

• 分配一致的 ID。如果您引用 Data view、库可视化等已保存对象，请使用 PUT (upsert) 并指定 ID 来创建这些对象，而不要使用会自动生成 ID 的 POST。使用易读的 ID（例如 logs-prod），这样更便于在不同环境中重复使用和识别。

有关这些可移植性模式以及完整的以代码形式管理仪表板的工作流的详细介绍，请参阅“以代码形式管理仪表板”文档。

使用 PUT 通过仪表板 API 创建 Kibana 仪表板

下面是一个简单示例：使用 PUT 而非 POST 创建包含指标面板的仪表板，并以仪表板名称 (service-health-overview) 作为自定义 ID。同样的逻辑也适用于创建保存到库中的独立可视化。

PUT kbn:/api/dashboards/service-health-overview
{
  "title": "服务运行状况概览",
  "description": "通过 API 管理的关键服务指标",
  "tags": [
    "production",
    "sre-team"
  ],
  "panels": [
    {
      "type": "vis",
      "grid": {
        "x": 0,
        "y": 0,
        "w": 12,
        "h": 8
      },
      "config": {
        "title": "错误率 (5xx)",
        "type": "metric",
        "data_source": {
          "type": "esql",
          "query": "FROM logs-* | WHERE http.response.status_code >= 500 | STATS error_rate=count(*) BY host.name"
        },
        "metrics": [
          {
            "type": "primary",
            "column": "count"
          }
        ]
      }
    }
  ]
}

Kibana 仪表板 API 路线图：Maps、Vega 和独立终端

我们正在积极扩展 API 的功能范围。下一步将支持 Maps 和 Vega 面板，并为其添加类型化架构。我们还在为 Discover 会话（除了现有的仪表板面板支持之外）、Vega、Maps 和注释构建独立的 CRUD 终端，使其与仪表板生命周期解耦。

有关完整的架构定义，请参阅仪表板 API 文档。对于 Terraform 用户，Elastic Stack Terraform 提供程序支持正式发布 (GA) 的仪表板 API。

注意

1. 核心终端自技术预览以来未发生变化。如果您基于 9.4 构建了集成，这些集成在 9.5 中也可正常运行。仅有两项轻微的破坏性变更，分别影响仪表板列表和时长单位格式，详见此处。