grafana-api

Grafana 的基础 URL 即其实例地址：Grafana Cloud 使用 https://<your-org>.grafana.net，自托管实例则使用组织运行它的地址 （例如 https://grafana.example.com）。API 接口相同；只有基础 URL 不同。

各端点的时间单位并不统一：/api/ds/query 和 /api/annotations 使用 Unix 毫秒；告警状态历史记录使用 Unix 秒；Alertmanager 静默使用 RFC-3339。混用会返回空结果，而不是错误。

请求设置

身份验证由运行时处理——凭据会注入发往此 API 的请求，因此无需进行任何设置。不要尝试创建、生成、刷新或验证令牌或密钥。 凭据变量仅用于确保请求格式正确；如果某个变量未设置，请将其设为任意占位值。持续出现 401/403 表示此工作区未配置凭据 ——请报告这一情况，而不要排查身份验证问题。

实例 URL 必须真实有效——它是每个请求路径的一部分：

export GRAFANA_URL="https://grafana.example.com"   # no trailing slash
export GRAFANA_TOKEN="placeholder"                 # injected by the runtime; any value works

每个请求：

curl -sS "${GRAFANA_URL}/api/..." -H "Authorization: Bearer ${GRAFANA_TOKEN}"

基本检查——确认 URL 正确，且工作区已接入：

curl -sS -w '\nHTTP %{http_code}\n' "${GRAFANA_URL}/api/user" -H "Authorization: Bearer ${GRAFANA_TOKEN}"
# 200 → the current user/service account. 401 → {"message":"Unauthorized"} — report it, don't debug auth.
# Service accounts also work: /api/org returns the current org.

403 通常意味着已配置的身份缺少所需角色（Viewer < Editor < Admin）。 数据源查询和仪表板读取只需要 Viewer。

下文会用到的辅助工具（可选）：

grafana() { curl -sS "$@" -H "Authorization: Bearer ${GRAFANA_TOKEN}"; }

核心操作

1. 搜索仪表板和文件夹

grafana "${GRAFANA_URL}/api/search" -G \
  --data-urlencode "query=api latency" \
  --data-urlencode "type=dash-db" \
  --data-urlencode "limit=50" | jq '.[] | {uid, title, folderTitle, url}'

type 为 dash-db（仪表板）或 dash-folder（文件夹）；省略时会搜索两者。此外还可使用：tag=, folderUIDs=, starred=true。

2. 按 UID 获取仪表板

UID 是仪表板 URL 中的短字符串：.../d/<uid>/<slug>。

grafana "${GRAFANA_URL}/api/dashboards/uid/abc123xy" | \
  jq '{title: .dashboard.title, folder: .meta.folderTitle, panels: [.dashboard.panels[]? | {id, title, type}]}'

每个面板的 PromQL/LogQL/SQL 位于 .dashboard.panels[].targets 下。UID 无效时会返回 {"message":"Dashboard not found"}（404）。

3. 执行数据源查询

通过这种方式，可以提出与面板相同的问题。首先查找数据源 UID：

grafana "${GRAFANA_URL}/api/datasources" | jq '.[] | {uid, name, type}'

然后向 /api/ds/query 发送 POST 请求。queries[] 的结构取决于数据源的 type；以下是 Prometheus 示例：

NOW_MS=$(( $(date +%s) * 1000 )); FROM_MS=$(( NOW_MS - 3600000 ))
grafana -X POST "${GRAFANA_URL}/api/ds/query" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "'"${FROM_MS}"'",
    "to": "'"${NOW_MS}"'",
    "queries": [{
      "refId": "A",
      "datasource": {"uid": "<datasource_uid>"},
      "expr": "sum(rate(http_requests_total{job=\"api\"}[5m])) by (status)",
      "intervalMs": 30000,
      "maxDataPoints": 500
    }]
  }' | jq '.results.A.error // .results.A.frames[0].data.values'

对于 Loki，请使用 "expr": "{job=\"api\"} |= \"error\""，并可选择设置 "queryType": "range"。对于 SQL 数据源，请使用 "rawSql": "SELECT ..." 和 "format": "table"。

响应采用 Grafana 数据帧格式：results.<refId>.frames[] 中包含平行的列数组（位于 data.values）， 列元数据则位于 schema.fields。数据源端发生故障时，frames 为空，Prometheus/Loki/SQL 返回的错误会嵌入 results.<refId>.error 中——HTTP 状态码仍可能是 200 或 500，因此应检查该字段，而不要只依赖状态码。

4. 列出告警规则

有两个用途不同的接口：

# live STATE (firing/pending/inactive) — read-only
grafana "${GRAFANA_URL}/api/prometheus/grafana/api/v1/rules" | \
  jq '.data.groups[]? | {folder: .file, group: .name, rules: [.rules[] | {name, state, health}]}'

# DEFINITIONS (query, condition, labels, for-duration) — full CRUD, no runtime state
grafana "${GRAFANA_URL}/api/v1/provisioning/alert-rules" | jq '.[] | {uid, title, folderUID, condition}'

第一个路径中的 grafana 部分是内置 Alertmanager 的字面值 {am_name}； 外部 Alertmanager 则使用其数据源 UID。通过配置 API 写入的资源在 UI 中处于锁定状态，除非写入时发送 X-Disable-Provenance: true。

5. 静默

startsAt/endsAt 使用 RFC-3339 格式（date -u +%Y-%m-%dT%H:%M:%SZ）。

# active silences
grafana "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" | \
  jq '.[] | select(.status.state=="active") | {id, comment, matchers, endsAt}'

# create a 2-hour silence matching a label
# GNU date; on BSD/macOS use: date -u -v+2H +%Y-%m-%dT%H:%M:%SZ
START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d "+2 hours" +%Y-%m-%dT%H:%M:%SZ)
grafana -X POST "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silences" \
  -H "Content-Type: application/json" \
  -d '{
    "matchers": [{"name": "alertname", "value": "HighErrorRate", "isRegex": false, "isEqual": true}],
    "startsAt": "'"${START}"'", "endsAt": "'"${END}"'",
    "createdBy": "api", "comment": "investigating"
  }'
# success → {"silenceID": "..."}

# expire a silence
grafana -X DELETE "${GRAFANA_URL}/api/alertmanager/grafana/api/v2/silence/<silence_id>"

6. 注释

time/timeEnd 使用 Unix 毫秒。

grafana -X POST "${GRAFANA_URL}/api/annotations" -H "Content-Type: application/json" \
  -d '{"time": '"$(( $(date +%s) * 1000 ))"', "tags": ["deploy","api"], "text": "Deployed v2.3.1"}'

grafana "${GRAFANA_URL}/api/annotations?from=${FROM_MS}&to=${NOW_MS}&tags=deploy" | jq .

7. 文件夹

grafana "${GRAFANA_URL}/api/folders" | jq '.[] | {uid, title}'
grafana -X POST "${GRAFANA_URL}/api/folders" -H "Content-Type: application/json" -d '{"title": "Team API"}'

8. 创建或更新仪表板

grafana -X POST "${GRAFANA_URL}/api/dashboards/db" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard": {"uid": null, "title": "My Dashboard", "panels": [], "schemaVersion": 41},
    "folderUid": "<folder_uid>",
    "overwrite": false,
    "message": "created via API"
  }'

要更新仪表板：先用 GET 获取仪表板，然后发送完整 JSON，并应用所需更改—— 此端点会替换整个仪表板。将 dashboard.uid 设为现有 UID，并包含当前的 dashboard.version（Grafana 不匹配时会返回 412）， 或者设置 overwrite: true。

分页

/api/search 和 /api/folders 使用 limit + page 查询参数（页码从 1 开始）。/api/search 默认值为 1000，上限为 5000。/api/annotations 提供 limit（默认值为 100），但没有 page—— 请缩小 from/to 时间范围。Alertmanager 端点不支持分页。达到上限时，请改用 query=, tag= 或 folderUIDs= 缩小范围，而不是翻阅所有页面。

速率限制

默认情况下，自托管的 Grafana 没有内置的逐令牌速率限制。Grafana Cloud 在 API 或查询流量较大时可能会返回 429 — 限制因套餐和端点而异；如果存在 Retry-After，请遵循其指示，否则请退避。 /api/ds/query 是开销较大的路径：每次调用都会将请求分发到底层数据库，因此请将多个 queries[] 批量放入一个请求中，而不是循环发送。

错误处理

错误响应体始终包含 "message"（有时还包含 "messageId"/"traceID"）。特定于服务的情况：

• 412 — 保存仪表板时发生版本冲突。获取最新版本，重新应用你的更改，包含 version，或设置 overwrite: true。
• 200/500 on /api/ds/query — 数据源端故障。Prometheus/Loki/SQL 错误包含在 results.<refId>.error 中；frames 为空。
• 403 — 角色权限不足。Viewer < Editor < Admin；文件夹级权限同样适用。

401 → 此工作区未配置凭据（请报告，不要排查）。UID 是区分大小写的短字符串，不是标题。

深入了解

references/api.md 包含完整的端点目录 — 仪表板、文件夹、数据源、各数据源对应的 ds/query 结构、完整的统一告警功能（告警规则、联系点、通知策略、静默时段、Alertmanager）、注释、快照、组织/用户/团队、服务账号和短 URL。需要使用上述端点以外的端点时，请阅读此文档。