4. 使用 cURL 导出仪表板：通过 API 导出单个仪表板的 JSON 模型，理解 JSON 结构

在 Grafana 的日常运维与跨环境同步场景中，API 导出是最直接、最可编程的获取仪表板定义的方式。相比 UI 手动导出，cURL 方式更适合集成到 CI/CD 流水线或自动化脚本中。本节将带你掌握通过 Grafana HTTP API 导出仪表板 JSON 的标准流程，并深入解析返回的 JSON 结构，为后续的模板化与同步打下基础。

4.1 导出仪表板的 API 端点与参数

Grafana 提供了两个核心端点用于获取仪表板定义，它们的返回格式略有不同：

其中 UID（Unique Identifier）是 Grafana 仪表板的唯一标识，在仪表板 URL 中可以直接看到，例如：/d/cXq4m6Z7z/my-dashboard 中的 cXq4m6Z7z 即为 UID。

4.2 使用 cURL 导出仪表板 JSON

以下是一个标准的 cURL 导出命令模板，请根据你的环境替换 GRAFANA_URL、 和 DASHBOARD_UID：

curl -s -H "Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxx" \
  "http://localhost:3000/api/dashboards/uid/cXq4m6Z7z" \
  | jq .

命令拆解：

• -s：静默模式，不显示进度信息。
• -H "Authorization: Bearer <>"：传递 进行身份认证。
• http://localhost:3000/api/dashboards/uid/cXq4m6Z7z：目标端点。
• | jq .：将返回的 JSON 进行格式化输出，便于阅读。

4.3 导出 JSON 的核心结构解析

成功导出后，你将得到一个类似如下的 JSON 结构（已简化关键字段）：

{
  "dashboard": {
    "id": 42,
    "uid": "cXq4m6Z7z",
    "title": "生产环境核心指标",
    "tags": ["production", "linux", "metrics"],
    "timezone": "browser",
    "schemaVersion": 36,
    "version": 7,
    "panels": [
      {
        "id": 1,
        "type": "graph",
        "title": "CPU 使用率",
        "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
        "targets": [
          {
            "expr": "100 - (avg by (instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)",
            "legendFormat": "{{ instance }}",
            "refId": "A"
          }
        ]
      }
    ],
    "templating": {
      "list": [
        {
          "name": "instance",
          "type": "query",
          "query": "label_values(node_cpu_seconds_total, instance)"
        }
      ]
    },
    "annotations": { "list": [] }
  },
  "meta": {
    "slug": "production-core-metrics",
    "folderTitle": "生产环境",
    "isStarred": false,
    "url": "/d/cXq4m6Z7z/production-core-metrics"
  }
}

关键字段说明：

4.4 导出流程可视化

下图展示了从发起 cURL 请求到获取完整仪表板 JSON 的完整数据流：

4.5 导出后的常见操作与注意事项

• 保存到文件：使用 curl ... > dashboard.json 将输出直接写入文件，便于后续处理。
• 提取纯 dashboard 对象：使用 jq '.dashboard' dashboard.json > dashboard_clean.json 去除 meta 信息，得到纯净的仪表板定义。
• 版本冲突处理：导入时如果 dashboard.version 与目标环境冲突，Grafana 会拒绝导入。建议在导出脚本中移除 version 字段，或将其重置为 0。
• UID 策略：跨环境同步时，如果希望保持仪表板 URL 一致，则保留 uid；如果希望目标环境生成新 UID，则删除 uid 字段。

4.6 理解 JSON 结构中的关键嵌套关系

仪表板 JSON 的层次结构可以抽象为以下逻辑模型，理解它将帮助你更精准地进行模板化改造：

从层次图中可以清晰看到：panels[] 是仪表板的核心，每个面板又包含 targets[]（查询语句）、gridPos（布局位置）和 type（面板类型）。templating 和 annotations 是全局配置，分别控制变量和事件标注。理解这个嵌套关系，是后续进行模板化替换和变量注入的前提。