> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 标签映射 API

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

## 一、功能概述

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

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

<span id="ApiSpec" />

## 二、API 规范

### 请求方式

<div class="md-block">
  POST, Content-Type:"application/json"
</div>

### 请求 Payload：

<div class="md-block">
  |          字段         |        类型       |  必含 | 释义                                |
  | :-----------------: | :-------------: | :-: | :-------------------------------- |
  | result\_label\_keys |    \[]string    |  是  | 期望返回的标签 Key 列表，由用户在 Flashduty 中配置 |
  |        event        | [Event](#Event) |  是  | 当前告警事件的完整信息                       |

  <span id="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     |  否  | 告警关联图片列表                          |
</div>

### 请求示例

<div class="md-block">
  ```json theme={null}
  {
    "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": []
    }
  }
  ```
</div>

### 响应规范

<div class="md-block">
  **成功响应：**

  |       字段       |         类型         |  必含 | 释义            |
  | :------------: | :----------------: | :-: | :------------ |
  | result\_labels | map\[string]string |  是  | 返回的增强标签 KV 对象 |

  * HTTP 状态码：`200 OK`
  * 响应体必须是包含 `result_labels` 字段的 JSON 对象
  * `result_labels` 的 Key 必须是请求中 `result_label_keys` 指定的标签名
  * 如果某个标签无法获取，**不应**在响应中包含该 Key

  **成功响应示例：**

  ```json theme={null}
  {
    "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` 状态码是更规范的做法。
</div>

<span id="ServiceConfig" />

## 三、配置映射服务

在 Flashduty 中配置标签映射时，您需要先创建一个映射服务，然后在标签增强规则中引用该服务。

### 映射服务字段说明

<div class="md-block">
  |           字段名          |         类型         |  必填 | 释义                                                |
  | :--------------------: | :----------------: | :-: | :------------------------------------------------ |
  |        api\_name       |       string       |  是  | 服务的可读名称，用于在 UI 中选择和引用，例如 "CMDB 资产查询 API"          |
  |       description      |       string       |  否  | 对该服务的详细描述                                         |
  |           url          |       string       |  是  | API 的请求 URL，支持使用模板变量                              |
  |         headers        | map\[string]string |  否  | HTTP 请求头，用于传递自定义认证信息，受[安全黑名单](#HeaderBlacklist)限制 |
  |         timeout        |         int        |  否  | 请求超时时间（单位：秒），可取值：1\~3                             |
  |      retry\_count      |         int        |  否  | 请求失败后的重试次数，可取值：0\~1                               |
  | insecure\_skip\_verify |        bool        |  否  | 请求 HTTPS 时跳过证书验证                                  |
  |         status         |       string       |  否  | 服务状态，如 enabled、disabled                           |
</div>

### 标签增强规则配置

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

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

<span id="HeaderBlacklist" />

## 四、Header 安全约束

为了防止安全绕过、请求走私、IP 伪造及缓存污染，在自定义 API 请求头时，**禁止**使用以下 Header。系统网关将自动过滤或拒绝包含这些 Header 的请求。

<div class="md-block">
  | 分类             | 禁用 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 协议差异进行的请求走私攻击      |
</div>

### 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 代码