Grafana 的新 API 结构

概览

今后，Grafana 的 HTTP API 将遵循标准化的 API 结构并采用一致的 API 版本控制。

API 路径结构

所有 Grafana API 都遵循此标准化格式

/apis/<group>/<version>/namespaces/<namespace>/<resource>[/<name>]

其中最后的 /<name> 段用于操作单个资源（如 Get、Update、Delete），对于集合操作（如 List、Create）则省略。

理解组件

组 (`<group>`)

组将相关功能组织到逻辑集合中。例如，dashboard.grafana.app 将用于所有与仪表盘相关的操作。

版本 (`<version>`)

这些 API 还将使用语义版本控制，具有三个稳定性级别

级别	格式	描述	用例
Alpha	`v1alpha1`	早期开发阶段。不稳定，可能包含错误，并可能移除	用于测试新功能
Beta	`v1beta1`	比 alpha 更稳定，但可能仍有部分变更	用于早期生产使用
GA	`v1`	正式发布。稳定，并保证向后兼容	用于生产使用

命名空间 (`<namespace>`)

命名空间隔离了 Grafana 实例中的资源。格式因部署类型而异

OSS 和本地部署的 Grafana

默认组织 (org 1): default
其他组织: org-<org_id>

Grafana Cloud

格式: stacks-<stack_id>
您的实例 ID 即 stack_id。您可以通过以下方式查找此值
- 访问 grafana.com，点击您的 stack，然后在您的 Grafana 实例上选择“Details”
- 访问您的 Cloud 实例中的 /swagger 页面，命名空间将在相关端点上自动填充

资源 (`<resource>`)

表示您想要交互的核心资源，例如

仪表盘 (dashboards)
播放列表 (playlists)
文件夹 (folders)

名称 ()

<name> 是资源在其命名空间和资源类型中的唯一标识符。<name> 不同于 metadata.uid 字段。URL 路径将始终使用 metadata.name。

例如，要获取定义为

{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1beta1",
  "metadata": {
    "name": "production-overview", // This value IS used in the URL path
    "namespace": "default",
    "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
    // ... other metadata
  },
  "spec": {
    // ... dashboard spec
  }
}

您将使用以下 API 调用

GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/production-overview