功能概述
映射标签规则类型需要专业版,控制台中显示 PRO 标记,其他版本无法选择。
- Flashduty 接收到告警事件
- 系统根据配置,将事件信息和期望获取的标签列表发送到您的 API
- 您的 API 查询外部数据源(如 CMDB、数据库等)
- API 返回计算得到的增强标签
- Flashduty 将返回的标签附加到告警上
配置步骤
1
在您的系统中实现标签映射接口
操作路径:您的服务 › 对外暴露的 HTTP 接口(Flashduty 服务端必须能访问)
接口须在步骤 2 配置的超时时间(1–3 秒)内返回,请求与响应的完整字段、示例见下文「API 规范」。
2
在 Flashduty 中创建映射 API
操作路径:配置中心 › 映射数据 › API › 创建 API
单个账户最多创建 50 个 API。创建元数据表(Schema)同样需要专业版。
3
在集成中添加标签映射规则
操作路径:Flashduty 控制台 › 集成中心 › 告警事件(专属集成:Flashduty 控制台 › 协作空间 › 配置 › 集成数据 › 专属集成)在右侧集成列表中点开要使用映射的集成,进入 标签增强 › 添加标签规则,规则类型选择 映射标签。配置标签增强规则时,只需要关注以下配置:
4
推送测试事件并确认标签
操作路径:Flashduty 控制台中该事件所生成告警的详情页向该集成推送一条满足规则条件的事件,在对应告警的详情中查看标签:接口返回的
result_labels。接口失败(超时、404、5xx)时告警照常处理,只是不附加增强标签,系统可能按重试次数重试。API 规范
请求方式
POST, Content-Type:“application/json”
请求 Payload
Event:
Image:
请求示例
响应规范
成功响应:失败响应:
- HTTP 状态码:
200 OK - 响应体必须是包含
result_labels字段的 JSON 对象 result_labels的 Key 必须是请求中result_label_keys指定的标签名- 如果某个标签无法获取,不应在响应中包含该 Key
提示: 返回200 OK状态码 + 空的result_labels: {}对象也会被视为”无结果”,但使用404状态码是更规范的做法。
Header 安全约束
为了防止安全绕过、请求走私、IP 伪造及缓存污染,在自定义 API 请求头时,禁止使用以下 Header。系统网关将自动过滤或拒绝包含这些 Header 的请求。Header 最佳实践
- 白名单模式:建议仅允许以
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 代码