一、功能概述
标签映射 API 允许您构建自定义的外部服务来增强告警标签。工作流程如下：
- Flashduty 接收到告警事件
- 系统根据配置，将事件信息和期望获取的标签列表发送到您的 API
- 您的 API 查询外部数据源（如 CMDB、数据库等）
- API 返回计算得到的增强标签
- Flashduty 将返回的标签附加到告警上
二、API 规范
请求方式
POST, Content-Type:“application/json”
请求 Payload：
| 字段 | 类型 | 必含 | 释义 |
|---|
| result_label_keys | []string | 是 | 期望返回的标签 Key 列表，由用户在 Flashduty 中配置 |
| event | Event | 是 | 当前告警事件的完整信息 |
| 字段 | 类型 | 必含 | 释义 |
|---|
| account_id | int64 | 是 | 账户 ID |
| channel_id | int64 | 是 | 协作空间 ID |
| data_source_id | int64 | 是 | 数据源 ID |
| data_source_type | string | 是 | 数据源类型，如 prometheus、zabbix 等 |
| title | string | 是 | 告警标题 |
| title_rule | string | 否 | 标题规则 |
| description | string | 否 | 告警描述 |
| alert_key | string | 是 | 告警唯一标识 |
| alert_id | string | 是 | 告警 ID |
| event_severity | string | 是 | 事件严重程度，枚举值：Critical、Warning、Info |
| event_status | string | 是 | 事件状态，枚举值：Critical、Warning、Info、Ok |
| event_time | int64 | 是 | 事件时间，Unix 秒时间戳 |
| labels | map[string]string | 否 | 告警原始标签 KV |
| images | []string | 否 | 告警关联图片列表 |
请求示例
{
"result_label_keys": ["owner_team", "service_tier", "host_ip"],
"event": {
"account_id": 1,
"channel_id": 20,
"data_source_id": 15,
"data_source_type": "prometheus",
"description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
"title": "High CPU Usage on instance 10.0.1.101:9100",
"title_rule": "",
"alert_key": "d41d8cd98f00b204e9800998ecf8427e",
"alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
"event_severity": "Critical",
"event_status": "Critical",
"event_time": 1678886400,
"labels": {
"region": "us-east-1",
"service": "service-A",
"env": "production",
"instance": "10.0.1.101:9100"
},
"images": []
}
}
响应规范
成功响应：| 字段 | 类型 | 必含 | 释义 |
|---|
| result_labels | map[string]string | 是 | 返回的增强标签 KV 对象 |
- HTTP 状态码：
200 OK
- 响应体必须是包含
result_labels 字段的 JSON 对象
result_labels 的 Key 必须是请求中 result_label_keys 指定的标签名- 如果某个标签无法获取，不应在响应中包含该 Key
成功响应示例：{
"result_labels": {
"owner_team": "team-database",
"service_tier": "tier-1",
"host_ip": "10.0.1.101"
}
}
| 状态码 | 含义 |
|---|
| 404 Not Found | 根据 event 信息无法找到任何可用于增强的数据 |
| 400 Bad Request | 请求体格式错误或 event 对象缺少关键字段 |
| 5xx | API 内部发生非预期的错误（如数据库连接失败） |
提示： 返回 200 OK 状态码 + 空的 result_labels: {} 对象也会被视为”无结果”，但使用 404 状态码是更规范的做法。
三、配置映射服务
在 Flashduty 中配置标签映射时，您需要先创建一个映射服务，然后在标签增强规则中引用该服务。
映射服务字段说明
| 字段名 | 类型 | 必填 | 释义 |
|---|
| api_name | string | 是 | 服务的可读名称，用于在 UI 中选择和引用，例如 “CMDB 资产查询 API” |
| description | string | 否 | 对该服务的详细描述 |
| url | string | 是 | API 的请求 URL，支持使用模板变量 |
| headers | map[string]string | 否 | HTTP 请求头，用于传递自定义认证信息，受安全黑名单限制 |
| timeout | int | 否 | 请求超时时间（单位：秒），可取值：1~3 |
| retry_count | int | 否 | 请求失败后的重试次数，可取值：0~1 |
| insecure_skip_verify | bool | 否 | 请求 HTTPS 时跳过证书验证 |
| status | string | 否 | 服务状态，如 enabled、disabled |
标签增强规则配置
配置标签增强规则时，只需要关注以下配置：
- result_label_keys：指定期望从 API 获取的标签列表，Flashduty 会自动将此列表和当前的
event 对象组合成请求体发送给您的 API
- 映射服务：选择或配置 API 服务的 URL、Headers 等信息
为了防止安全绕过、请求走私、IP 伪造及缓存污染，在自定义 API 请求头时，禁止使用以下 Header。系统网关将自动过滤或拒绝包含这些 Header 的请求。
| 分类 | 禁用 Header | 风险说明 |
|---|
| 认证与授权 | authorization, proxy-authorization, cookie, x-api-key, x-access-token | 防止凭证泄露或非法劫持已有的认证上下文 |
| IP 与地理位置伪造 | x-forwarded-for, x-real-ip, true-client-ip, x-client-ip | 防止客户端伪造来源 IP 以绕过频率限制或黑白名单 |
| 主机与路由操控 | host, x-forwarded-host, x-forwarded-proto, x-internal-id, x-user-id | 防止 Host 注入攻击、重定向循环或伪造内部系统 ID |
| 协议与请求走私 | transfer-encoding, upgrade, connection | 防止利用 HTTP 协议差异进行的请求走私攻击 |
- 白名单模式：建议仅允许以
X-Custom- 或 X-Enrich- 为前缀的自定义 Header
- 长度限制：单个 Header 的 Key 或 Value 长度不应超过 1024 字节
- 格式校验：Header 的 Value 严禁包含换行符（
\r、\n），以防止 Header 注入攻击
五、最佳实践
-
性能优先： 此 API 位于告警处理的关键路径上，必须保证低延迟。对外部数据源的查询应尽可能快，建议实现缓存机制。
-
明确的错误处理： 善用 HTTP 状态码（特别是
404）来传递清晰的执行结果。
-
幂等性： API 的设计应尽可能幂等。对于同一个
event，多次调用应返回相同的结果。
-
安全性： API 必须通过认证和授权机制进行保护，推荐使用自定义 Header（如
X-Custom-Auth）传递认证信息。
六、常见问题
-
服务是否有响应超时时间？
- 服务需要在配置的超时时间内返回响应，超时则认为响应失败
-
如果 API 返回失败会怎样？
- 告警会正常处理，但不会附加增强标签
- 根据配置的重试次数，系统可能会重试请求
-
result_label_keys 可以动态变化吗？
- 是的，您可以在 Flashduty 中随时修改期望获取的标签列表，无需修改 API 代码
