> ## 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.

# HTTP 拉取告警 (HTTP Pull)

> Flashduty 主动按周期访问外部 HTTP 接口，将返回的告警事件拉取入库；适用于无法主动推送告警的系统，或希望将拉取与推送解耦的场景。

通过配置一个 HTTP 端点，Flashduty 会按照您设定的周期主动发起请求，将响应解析为符合 [标准告警事件](/zh/on-call/integration/alert-integration/alert-sources/standard%20alert) 协议的事件并写入告警通道。整个过程不需要您的系统具备推送能力，只要能对外暴露一个可读的告警查询接口即可。

<Tip>
  HTTP 拉取适合 **无法主动 webhook**、**接口本身就是查询型** 或 **不希望对告警源做改造** 的场景。如果您的系统已经支持 webhook 推送，优先使用对应的推送式集成（Prometheus、Zabbix 等），延迟更低、资源开销更小。
</Tip>

## 操作步骤

***

### 在 Flashduty

<AccordionGroup>
  <Accordion title="使用专属集成">
    当您不需要根据告警内容路由到不同的协作空间时，优先选择此方式，更简单。

    1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面。
    2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面。
    3. 选择 **HTTP Pull** 集成。
    4. 按下文「配置项」说明填写表单，点击 **保存**。
  </Accordion>

  <Accordion title="使用共享集成">
    当您需要根据告警事件的 Payload 信息，将告警路由到不同协作空间时，优先选择此方式。

    1. 进入 Flashduty 控制台，选择 **集成中心 ⇒ 告警事件**，进入集成选择页面。
    2. 选择 **HTTP Pull** 集成，并填写 **集成名称**。
    3. 配置 **默认路由**，选择对应的协作空间（集成创建后可前往 **路由** 配置更多路由规则）。
    4. 按下文「配置项」说明填写表单，点击 **保存** 完成。
  </Accordion>
</AccordionGroup>

## 配置项

***

### HTTP 请求

|    字段   |        必填       |  默认值  | 说明                                                                                                                            |
| :-----: | :-------------: | :---: | :---------------------------------------------------------------------------------------------------------------------------- |
|   URL   |        是        |   -   | 拉取告警的目标地址，必须以 `http` 或 `https` 开头。支持 Go 模板变量，详见下文「模板变量」。例如：`https://example.com/api/alerts?cursor={{.PageValue}}`。            |
|   请求方法  |        是        | `GET` | 仅支持 `GET` 或 `POST`。                                                                                                           |
|   请求头   |        否        |   -   | Key-Value 列表，常用于携带鉴权信息（`Authorization`、`X-Api-Key` 等）。                                                                        |
|   请求体   | 当方法为 `POST` 时必填 |   -   | 任意字符串，通常为 JSON。当启用游标分页且 **注入位置** 为 `Body` 时，Body 中 **必须** 包含 `{{.PageValue}}` 占位符，例如 `{"cursor":"{{.PageValue}}"}`，否则表单会校验失败。 |
| 超时时间（秒） |        是        |  `10` | 单次 HTTP 请求的超时时间，取值范围 `1 ~ 300`。                                                                                               |
|   重试次数  |        是        |  `0`  | 单次拉取失败时的重试次数，取值范围 `0 ~ 10`。                                                                                                   |
| 拉取周期（秒） |        是        |  `60` | Flashduty 触发下一次拉取的间隔，**最小值 30 秒**。                                                                                            |

### 分页配置

很多查询型接口在单次返回时会做条数限制，需要按游标分页才能拿到完整数据。Flashduty 支持基于游标的分页：每次响应中提取下一页游标，注入到下一次请求里，直到响应中不再返回游标或达到上限。

|   字段  |           必填          |     默认值     | 说明                                                                                   |
| :---: | :-------------------: | :---------: | :----------------------------------------------------------------------------------- |
|  分页模式 |           是           |    `无分页`    | `无分页`（`none`）：一次请求结束即停止；`游标分页`（`cursor`）：启用游标分页。                                     |
|  游标路径 |        启用分页时必填        |      -      | 从响应 JSON 中提取下一页游标值的字段路径，使用点号分隔，例如 `pagination.next_cursor`。                          |
|  注入位置 |        启用分页时必填        | `URL Query` | 下一次请求时游标值的放置位置。`URL Query`：以查询参数追加到 URL；`Body`：合并进请求体。当请求方法为 `GET` 时强制为 `URL Query`。 |
|  参数名  | 注入位置为 `URL Query` 时必填 |      -      | 注入到 URL Query 的参数名，例如 `cursor`。当 **注入位置** 为 `Body` 时，参数名由您的 Body 模板自行约定，无需在此填写。      |
| 最大分页数 |        启用分页时必填        |     `20`    | 单次拉取最多翻多少页，取值范围 `1 ~ 100`。达到上限或响应中提取不到下一页游标时，本轮分页停止。                                 |

### 严重程度映射

外部系统的告警级别字段名称、取值往往不一致，Flashduty 通过 **严重程度映射** 将外部值翻译为标准的 `Critical / Warning / Info`。

* 系统读取响应中的 `event_status` 字段值（标准告警事件协议中的告警级别字段），按映射表查找对应的 Flashduty 严重程度。
* **默认映射**：`P1 → Critical`、`P2 → Warning`、`P3 → Info`。您可以删除默认项、新增任意条目。
* **未命中兜底**：如果响应中的 `event_status` 没有命中映射表中的任何 Key，将统一降级为 `Warning`。

### 响应格式

接口响应必须符合 Flashduty 的 [标准告警事件](/zh/on-call/integration/alert-integration/alert-sources/standard%20alert) 协议（`response_mode = standard`），核心字段包括 `event_status`、`title_rule`、`alert_key`、`description`、`labels` 等。请直接参考标准告警事件文档了解每个字段的语义与长度限制。

启用分页时，您的响应需要在标准事件载荷之外，额外暴露一个用于提取下一页游标的字段，路径由 **游标路径** 指定。常见的形态如下：

```json theme={null}
{
  "alerts": [
    { "event_status": "Critical", "title_rule": "cpu idle low than 20%", "alert_key": "host-1" },
    { "event_status": "Warning",  "title_rule": "disk usage > 80%",      "alert_key": "host-2" }
  ],
  "pagination": {
    "next_cursor": "eyJvZmZzZXQiOjEwMH0="
  }
}
```

## 默认路由

***

新增「共享集成」（即在 **集成中心 ⇒ 告警事件** 中创建）时，必须配置默认路由，否则新拉取到的事件将被丢弃。集成创建后可在 **路由** 中追加更细粒度的规则。

「专属集成」（在某个协作空间的 **集成数据** 中创建）会自动绑定到所在空间，不需要单独配置默认路由。

## 模板变量

***

URL 与请求体支持 Go 模板语法。当前仅有 **一个** 内置变量：

|        变量        | 说明                                                                  |
| :--------------: | :------------------------------------------------------------------ |
| `{{.PageValue}}` | 当前请求要发送的分页游标值。**首次请求时该变量为空字符串**；后续每次请求会使用上一次响应中按 **游标路径** 提取的值进行渲染。 |

使用规则：

* 启用游标分页时，必须在 URL（注入位置为 `URL Query`）或 Body（注入位置为 `Body`）中至少出现一次 `{{.PageValue}}`，否则下一页游标无法生效。
* `GET` 请求自动将注入位置锁定为 `URL Query`，但仍需您自行决定把变量写在 URL 的哪个查询参数上，或直接使用 **参数名** 让系统拼接。
* 不启用分页（`无分页` 模式）时，该变量始终渲染为空字符串。