HTTP API 与自动化

能力边界与文档入口

Grafana 内置一套 REST API，仪表盘、数据源、用户、组织、告警等资源均可读写；完整的端点参考在实例的 /api-docs 页面与官方 HTTP API 文档。批量迁移、CI 里校验仪表盘 JSON、对接工单系统，基本都从这里入手。

认证：优先服务账号

Bearer Token 的用法统一是 Authorization: Bearer <token>。先创建一个服务账号并发 Token：

# 建服务账号，拿到数据库里的 id
curl -X POST "$GRAFANA/api/serviceaccounts" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","role":"admin","kind":"admin"}'

# 用返回的 id 换 Token（只显示一次，妥善保存）
curl -X POST "$GRAFANA/api/serviceaccounts/5/tokens" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"ci-token","role":"admin"}'

三个常用示例

# 1. 创建用户并设密码
curl -X POST "$GRAFANA/api/admin/users" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"zhang-san","login":"zhangsan","password":"...","email":"zs@example.com"}'

# 2. 列出全部仪表盘（搜索端点，starred/_tag 等参数可过滤）
curl -H "Authorization: Bearer $TOKEN" "$GRAFANA/api/search?type=dash-db&limit=1000"

# 3. 修改数据源：先 GET 拿到完整对象，改后整体 PUT 回去
curl -H "Authorization: Bearer $TOKEN" "$GRAFANA/api/datasources/uid/P297C7ABF4658D8C7" -o ds.json
# ...编辑 ds.json 的 url 字段...
curl -X PUT "$GRAFANA/api/datasources/1" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @ds.json

常用端点速查

速率、分页与幂等

• 速率限制：新版实例可在配置中启用 API 限流，脚本批量调用前先确认策略（见配置文件 grafana.ini），收到 429 时退避重试而不是死循环。
• 分页：列表类端点风格不一。/api/search 用 limit，用户/团队类用 page + per_page，拿到结果先数一数是不是恰好一页，再判断要不要翻页。
• 幂等：POST /api/dashboards/db 同 uid 重复提交即更新，放心用于 CI；带 overwrite: true 可跳过版本冲突。

注意： 用 API 写仪表盘时 JSON 里的 version 字段管理并发，脚本请先 GET 再改再 POST，避免用缓存的旧 JSON 覆盖别人的修改。

下一步

• 配置层的自动化走Provisioning：配置即代码。
• 批量导出仪表盘做迁移，读迁移与备份。
• 用户与权限模型，看用户管理与角色与权限。