📚 课程目录第2章 Grafana API基础

2. Grafana API 基础：认证方式、请求与响应格式、HTTP 状态码约定

在调用 Grafana 告警规则接口之前，必须掌握 API 的认证机制、数据交换格式以及状态码语义。本章将围绕这三种基础能力展开，确保后续的告警规则增删改查操作能够正确、安全地执行。

2.1 API 认证方式

Grafana 提供三种主流的 API 认证方式，适用于不同的使用场景：自动化脚本、CI/CD 流水线、以及人工调试。下表对比了三种方式的差异：

认证方式	凭证载体	适用场景	安全等级	有效期
	请求头 `Authorization: Bearer <key>`	自动化脚本、第三方集成	中	可设置过期时间（1 天 ~ 永久）
Basic Auth	请求头 `Authorization: Basic <base64>`	快速测试、curl 调试	低（需配合 HTTPS）	随用户密码变更而失效
（Service Account）	请求头 `Authorization: Bearer <>`	生产环境、细粒度权限控制	高	可设置过期时间，支持轮换

推荐实践：生产环境中优先使用 Service Account 。在 Grafana 9.x 之后逐步被 Service Account 替代，新项目应直接使用方式。

2.1.1 认证

是 Grafana 早期提供的静态密钥，通过 Grafana UI 的 "Configuration → s" 创建。使用时在请求头中携带：

curl -X GET "https://grafana.example.com/api/rules" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2.1.2 Basic Auth 认证

使用 Grafana 用户名和密码进行 Base64 编码后传递。适用于快速验证接口连通性：

curl -X GET "https://grafana.example.com/api/rules" \
  -u "admin:your_password"

注意：Basic Auth 会将明文密码暴露在请求头中，必须配合 HTTPS 使用，且不建议在生产自动化流程中使用。

2.1.3 Service Account 认证

Service Account 是 Grafana 8.5+ 引入的现代化认证方式。在 "Administration → Service Accounts" 中创建账号并生成。可以绑定特定角色（Viewer / Editor / Admin），实现最小权限原则：

curl -X GET "https://grafana.example.com/api/rules" \
  -H "Authorization: Bearer glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  认证方式选择流程图： 以下 SVG 展示了从场景到认证方式的决策路径。

2.2 请求与响应格式

Grafana API 遵循 RESTful 设计原则，所有告警规则相关的接口统一使用 JSON 作为数据交换格式。请求和响应必须设置正确的 Content-Type。

2.2.1 请求头规范

请求头	必填	值示例	说明
`Authorization`	是	`Bearer glsa_xxx`	认证凭证
`Content-Type`	是（POST/PUT/PATCH）	`application/json`	请求体格式
`Accept`	否	`application/json`	期望的响应格式

2.2.2 请求体结构（以创建告警规则为例）

POST /api/v1/provisioning/alert-rules
Content-Type: application/json
Authorization: Bearer glsa_xxxxxxxxxx

{
  "title": "CPU 使用率过高",
  "condition": "A",
  "data": [
    {
      "refId": "A",
      "queryType": "",
      "relativeTimeRange": {
        "from": 600,
        "to": 0
      },
      "datasourceUid": "ds_prometheus_01",
      "model": {
        "expr": "avg by(instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) < 0.2"
      }
    }
  ],
  "noDataState": "NoData",
  "execErrState": "Error",
  "for": "5m",
  "annotations": {
    "summary": "实例 {{ $labels.instance }} CPU 使用率超过 80%"
  },
  "labels": {
    "severity": "critical",
    "team": "infra"
  }
}

2.2.3 响应体结构

成功的响应通常包含以下字段：

{
  "id": 42,
  "uid": "abc123def456",
  "title": "CPU 使用率过高",
  "condition": "A",
  "data": [ ... ],
  "for": "5m",
  "noDataState": "NoData",
  "execErrState": "Error",
  "annotations": { ... },
  "labels": { ... },
  "created": "2025-01-15T10:30:00Z",
  "updated": "2025-01-15T10:30:00Z"
}

关键字段说明：
uid：告警规则的全局唯一标识符，后续更新、删除操作均依赖此字段。
for：告警触发后持续满足条件的时间，用于防止抖动。
noDataState / execErrState：数据缺失或查询错误时的处理策略。

2.3 HTTP 状态码约定

Grafana 告警规则接口遵循标准的 HTTP 状态码语义。理解这些状态码有助于快速定位调用问题。

状态码	含义	典型场景	处理建议
200 OK	请求成功	GET 查询、PUT 更新	正常解析响应体
201 Created	资源创建成功	POST 创建告警规则	从响应头 `Location` 或响应体获取新资源 UID
204 No Content	删除成功	DELETE 删除告警规则	无需解析响应体
400 Bad Request	请求参数错误	缺少必填字段、JSON 格式错误	检查请求体结构，参考错误消息中的 `message` 字段
401 Unauthorized	认证失败	过期、无效	重新生成凭证，检查 `Authorization` 头
403 Forbidden	权限不足	Service Account 角色为 Viewer 却尝试创建规则	提升 Service Account 角色至 Editor 或 Admin
404 Not Found	资源不存在	使用错误的 UID 查询告警规则	确认 UID 是否正确，或资源已被删除
409 Conflict	资源冲突	创建规则时标题与已有规则重复	修改标题或使用 `PUT` 更新已有规则
429 Too Many Requests	请求频率超限	短时间内大量调用 API	降低请求频率，检查 `Retry-After` 响应头
500 Internal Server Error	服务端内部错误	Grafana 后端异常、数据库连接失败	检查 Grafana 日志，确认后端服务状态

避坑提示：

收到 401 时，优先检查是否已过期，而非盲目重试。
收到 409 时，不要直接删除重试，应使用 PUT /api/v1/provisioning/alert-rules/{uid} 进行幂等更新。
告警规则接口的 429 限流阈值默认为 100 次/分钟，可通过 Grafana 配置文件中的 api_rate_limit 调整。

2.4 状态码与认证方式的关系图

以下 SVG 展示了不同认证方式下，请求经过 Grafana API 网关时的状态码流转路径：

2.5 本章小结

认证方式：生产环境优先使用 Service Account ，开发调试可用或 Basic Auth。
请求格式：所有告警规则接口使用 JSON，必须设置 Content-Type: application/json。
状态码：牢记 200/201/204 表示成功，401/403 表示认证或权限问题，400/409 表示请求参数问题，429 表示限流。
幂等性：创建使用 POST，更新使用 PUT（全量替换），删除使用 DELETE。更新和删除操作依赖 uid 字段。