标签映射 API

配置标签映射 API，当告警事件到达时，Flashduty 将自动调用您配置的外部 API 获取增强标签，实现告警信息的动态丰富和关联。通过此功能，您可以将 CMDB、HR 系统等外部数据源的信息自动附加到告警上。

​

一、功能概述

标签映射 API 允许您构建自定义的外部服务来增强告警标签。工作流程如下：

1. Flashduty 接收到告警事件
2. 系统根据配置，将事件信息和期望获取的标签列表发送到您的 API
3. 您的 API 查询外部数据源（如 CMDB、数据库等）
4. API 返回计算得到的增强标签
5. Flashduty 将返回的标签附加到告警上

​

二、API 规范

​

请求方式

POST, Content-Type:“application/json”

​

请求 Payload：

字段	类型	必含	释义
result_label_keys	[]string	是	期望返回的标签 Key 列表，由用户在 Flashduty 中配置
event	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

​

标签增强规则配置

配置标签增强规则时，只需要关注以下配置：

1. result_label_keys：指定期望从 API 获取的标签列表，Flashduty 会自动将此列表和当前的 event 对象组合成请求体发送给您的 API
2. 映射服务：选择或配置 API 服务的 URL、Headers 等信息

​

四、Header 安全约束

为了防止安全绕过、请求走私、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 协议差异进行的请求走私攻击

​

Header 最佳实践

1. 白名单模式：建议仅允许以 X-Custom- 或 X-Enrich- 为前缀的自定义 Header
2. 长度限制：单个 Header 的 Key 或 Value 长度不应超过 1024 字节
3. 格式校验：Header 的 Value 严禁包含换行符（\r、\n），以防止 Header 注入攻击

​

五、最佳实践

1. 性能优先： 此 API 位于告警处理的关键路径上，必须保证低延迟。对外部数据源的查询应尽可能快，建议实现缓存机制。

2. 明确的错误处理： 善用 HTTP 状态码（特别是 404）来传递清晰的执行结果。

3. 幂等性： API 的设计应尽可能幂等。对于同一个 event，多次调用应返回相同的结果。

4. 安全性： API 必须通过认证和授权机制进行保护，推荐使用自定义 Header（如 X-Custom-Auth）传递认证信息。

​

六、常见问题

1. 服务是否有响应超时时间？

   • 服务需要在配置的超时时间内返回响应，超时则认为响应失败

2. 如果 API 返回失败会怎样？

   • 告警会正常处理，但不会附加增强标签
   • 根据配置的重试次数，系统可能会重试请求

3. result_label_keys 可以动态变化吗？

   • 是的，您可以在 Flashduty 中随时修改期望获取的标签列表，无需修改 API 代码