3. Grafana API 入门：API 认证方式与常用端点

跨环境同步的核心是程序化地操作 Grafana 资源，而 Grafana HTTP API 是实现这一目标的唯一通道。本章将带你掌握 API 的两种认证方式，并熟练使用搜索、获取、创建仪表板这三个最常用的端点，为后续的自动化同步脚本打下基础。

3.1 API 认证方式

Grafana API 默认不对外开放匿名访问，所有请求必须携带有效的认证凭证。官方提供两种主流认证方式： 和 Basic Auth。下表从安全性、适用场景和生命周期三个维度进行对比：

3.1.1 创建与使用

在 Grafana Web UI 中，通过 Configuration → s → Add 创建。创建时需指定名称、角色（Admin / Editor / Viewer）和过期时间。创建成功后，Key 仅显示一次，务必立即保存。

在 HTTP 请求中，通过 Authorization 头传递：

# 使用 curl 请求示例
curl -X GET "http://your-grafana:3000/api/search" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3.1.2 使用 Basic Auth

适用于快速验证或无法创建 的受限环境。将用户名和密码拼接为 username:password 后进行 Base64 编码：

# 使用 curl 的 -u 参数自动处理 Base64 编码
curl -X GET "http://your-grafana:3000/api/search" \
  -u "admin:admin123"

3.2 常用 API 端点详解

Grafana API 覆盖了仪表板、数据源、组织、用户等全部资源。在跨环境同步流程中，以下三个端点构成了核心操作循环：搜索 → 获取 → 创建/更新。

3.2.1 搜索仪表板：GET /api/search

该端点返回当前组织中所有可访问的仪表板列表，支持按文件夹、标签、名称进行过滤。响应结果包含每个仪表板的 uid、title、folderUid 等关键字段。

常用查询参数：

• query：按名称模糊搜索
• folderIds：按文件夹 ID 过滤
• tag：按标签过滤（可重复使用）
• type：dash-db（仪表板）或 dash-folder（文件夹）

# 搜索名称包含 "nginx" 的所有仪表板
curl -s -X GET "http://your-grafana:3000/api/search?query=nginx&type=dash-db" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxx" | jq '.[] | {uid, title, folderUid}'

3.2.2 获取仪表板：GET /api/dashboards/uid/:uid

通过搜索得到的 uid，获取单个仪表板的完整定义。响应体包含两个重要部分：

• dashboard：仪表板 JSON 模型（包含 panels、templating、annotations 等）
• meta：元数据（版本号、是否被星标、所属文件夹路径等）

# 获取指定 uid 的仪表板完整 JSON
curl -s -X GET "http://your-grafana:3000/api/dashboards/uid/abc123" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxx" | jq '.dashboard' > dashboard.json

3.2.3 创建/更新仪表板：POST /api/dashboards/db

该端点同时支持创建和更新操作。请求体必须包含 dashboard 对象和 overwrite 标志：

• 创建新仪表板：提供 dashboard JSON，不设置 uid 或使用新 uid，overwrite: false
• 更新已有仪表板：提供完整的 dashboard JSON（包含现有 uid 和正确的 version），overwrite: true

# 创建新仪表板（从文件读取 JSON）
curl -s -X POST "http://your-grafana:3000/api/dashboards/db" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {
      "title": "Nginx 监控（同步测试）",
      "tags": ["nginx", "synced"],
      "panels": [],
      "timezone": "browser"
    },
    "overwrite": false,
    "folderUid": "folder123"
  }' | jq '.uid'

3.3 认证方式与端点组合实战

下面的 SVG 图展示了两种认证方式如何与三个核心端点组合，形成完整的跨环境同步数据流：

3.4 常见错误与排查