4. 告警降噪标准模板接口总览：接口清单、接口调用流程、接口返回码定义、接口鉴权方式

本章节聚焦于告警降噪标准模板的接口体系，为后续的工程案例调用提供完整的接口参考。我们将从接口清单、调用流程、返回码定义及鉴权方式四个维度展开，确保读者能够快速上手并正确集成。

4.1 接口清单

标准模板提供以下核心RESTful接口，所有接口均以 /api/v1/noise-reduction 为基路径。

序号	接口名称	HTTP方法	接口路径	功能描述
1	创建降噪规则	POST	/rules	创建一条新的告警降噪规则，包含聚合、过滤、抑制策略
2	查询规则列表	GET	/rules	分页查询当前租户下的所有降噪规则
3	更新规则	PUT	/rules/{ruleId}	更新指定规则的配置参数
4	删除规则	DELETE	/rules/{ruleId}	删除指定规则
5	触发降噪评估	POST	/evaluate	对传入的告警事件列表执行降噪规则评估，返回降噪结果
6	查询降噪历史	GET	/history	查询指定时间范围内的降噪操作记录
7	获取模板元数据	GET	/template-meta	获取当前标准模板的版本、支持的规则类型等元信息

4.2 接口调用流程

标准模板的接口调用遵循统一的请求-响应生命周期，整体流程如下图所示：

调用流程分为以下五个步骤：

1. 发起请求：客户端构建HTTP请求，包含请求头（Authorization ）、请求体（JSON格式）。
2. 鉴权校验：鉴权网关解析，校验身份与权限，若失败则直接返回401错误。
3. 路由与限流：API网关根据路径将请求转发至对应服务，并执行令牌桶限流策略。
4. 业务处理：降噪引擎执行规则匹配、聚合、过滤等核心逻辑。
5. 数据持久化与响应：将操作记录写入数据库，并返回标准响应体给客户端。

4.3 接口返回码定义

所有接口采用统一的返回码体系，响应体结构固定为：

{
  "code": 0,
  "message": "success",
  "requestId": "a1b2c3d4-...",
  "data": { ... }
}

返回码 (code)	含义	说明
0	成功	请求处理成功，data字段包含有效数据
1001	参数校验失败	请求体缺少必填字段或字段格式错误
1002	规则不存在	指定的 ruleId 在系统中未找到
2001	鉴权失败	无效、过期或权限不足
2002	请求被限流	当前租户请求频率超过阈值，请稍后重试
3001	内部服务错误	降噪引擎或数据库异常，请联系管理员
3002	依赖服务超时	调用外部依赖（如CMDB）超时，建议重试

4.4 接口鉴权方式

标准模板接口采用 Bearer 鉴权方式，所有请求必须在HTTP Header中携带有效的访问令牌。

4.4.1 获取

调用方需先通过OAuth2.0客户端凭证模式获取：

POST /auth/oauth/
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret

响应示例：

{
  "access_": "eyJhbGciOiJIUzI1NiIs...",
  "_type": "Bearer",
  "expires_in": 3600
}

4.4.2 请求携带

在调用降噪接口时，将放入请求头：

GET /api/v1/noise-reduction/rules
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

4.4.3 鉴权失败处理

当无效或过期时，接口返回 2001 错误码。客户端应捕获该错误并重新获取后重试。