From 160a7f1d3fd28db75fd63191150a300b62ef0888 Mon Sep 17 00:00:00 2001 From: pijiang <419471640@qq.com> Date: Fri, 22 May 2026 14:31:49 +0800 Subject: [PATCH] update http-pull docs --- .../8.1.60 Http Pull Alert Integration.md | 234 +++++++++++------- ...12\350\255\246\351\233\206\346\210\220.md" | 221 ++++++++++------- 2 files changed, 273 insertions(+), 182 deletions(-) diff --git a/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.60 Http Pull Alert Integration.md b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.60 Http Pull Alert Integration.md index 41456e37..8c210b84 100644 --- a/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.60 Http Pull Alert Integration.md +++ b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.60 Http Pull Alert Integration.md @@ -1,28 +1,85 @@ --- -title: "HTTP Pull alert integration" +title: "HTTP Pull Alert Integration" description: "Ingest alert events by periodically pulling from an external HTTP endpoint, ideal for systems that cannot push alerts." +date: "2025-05-22T10:00:00+08:00" +url: "https://docs.flashcat.cloud/en/flashduty/http-pull-integration-guide" --- -**Plan requirement**: HTTP Pull integration requires a Pro or higher On-call plan. +Ingest alert events by periodically pulling from an external HTTP endpoint, ideal for systems that cannot push alerts. + +:::tips +HTTP Pull integration requires a Pro or higher On-call plan. +::: + +
+ +## In Flashduty +--- + +You can obtain an integration push URL through either of these two methods: + +### Using Private Integration + +Choose this method when you don't need to route alert events to different channels - it's simpler. + +
+ Expand + + 1. Go to the Flashduty console, select **Channel**, and enter a specific channel's details page + 2. Select the **Integrations** tab, click **Add Integration** to enter the integration page + 3. Choose **HTTP Pull** integration, click **Save** to generate a card + 4. Click the generated card to view the **Push URL**, copy it for later use + +
+ +### Using Shared Integration + +Choose this method when you need to route alerts to different channels based on alert event payload information. + +
+ Expand + + 1. Go to the Flashduty console, select **Integration Center => Alert Events** to enter the integration selection page + 2. Select **HTTP Pull** integration: + - **Integration Name**: Define a name for this integration + 3. Configure the default route and select the corresponding channel (after the integration is created, you can go to `Route` to configure more routing rules) + 4. Click **Save** and copy the newly generated **push URL** for later use + 5. Done + +
+
+ +## Overview +--- + +
Flashduty supports two alert ingestion modes: **Push** and **Pull**. Most integrations use the push mode, where the external monitoring system actively sends alerts to Flashduty. However, some systems do not support webhook push, or alert data can only be retrieved through an API query. HTTP Pull integration is designed for these scenarios — you simply provide an HTTP endpoint that returns alert data in JSON format, and Flashduty will periodically pull the data on a schedule you define, converting it into standard alert events for processing. -## Use cases +### Use Cases - The monitoring system only provides a query API and does not support webhook push - Alert data is stored in a database or object storage and must be queried via an HTTP endpoint - A custom system cannot be retrofitted for push mode yet, and you want to integrate quickly via pull -## Configuration steps +### Configuration Steps - - -Go to the Flashduty console, navigate to **Integration Center → Alert Events**, search for and select the **HTTP Pull** integration. - +1. Go to the Flashduty console, navigate to **Integration Center → Alert Events**, search for and select the **HTTP Pull** integration +2. Configure request parameters (see [Request Parameters](#request-parameters)) +3. Set the **pull cycle (cycle_seconds)** — how often data is pulled. Minimum is 30 seconds, default is 300 seconds (5 minutes) +4. Configure severity mapping if needed (see [Severity Mapping](#severity-mapping)) +5. Configure pagination if your endpoint supports it (see [Pagination Configuration](#pagination-configuration)) +6. Click **Save** to enable the integration. You can also manually trigger a pull from the integration details page + +
+ +## I. Request Parameters +--- + +
- Configure the parameters Flashduty uses when making requests to your endpoint: | Parameter | Required | Description | @@ -34,30 +91,12 @@ Configure the parameters Flashduty uses when making requests to your endpoint: | **Timeout** | No | Per-request timeout, 1–10 seconds. Defaults to 5 seconds | | **RetryCount** | No | Number of retries on failure, 0–2. Defaults to 1 | - - - -Set the **pull cycle (cycle_seconds)** — how often data is pulled. Minimum is 30 seconds, default is 300 seconds (5 minutes). - - - -If the severity values returned by your endpoint differ from Flashduty's standard, use **severity_mapping** to map them. - -For example, if your system uses `high` / `medium` / `low`, you can map them to Flashduty's `Critical` / `Warning` / `Info`. - +
- -If your endpoint supports pagination, configure pagination parameters to retrieve complete data. See [Pagination configuration](#pagination-configuration) for details. - - - -After saving, the integration will automatically pull data on the configured schedule. You can also manually trigger a pull from the integration details page. - - - -## Response format requirements +## II. Response Format Requirements +--- - +
Your HTTP endpoint must meet the following requirements: @@ -89,23 +128,24 @@ Each element in `items` corresponds to one alert event. The fields are consisten } ``` -### Event field reference +### Event Field Reference -| Field | Required | Type | Description | -| :--- | :--- | :--- | :--- | -| event_status | Yes | string | Alert status. Enum (capitalized): `Critical`, `Warning`, `Info`, `Ok` (recovery) | -| title_rule | Yes | string | Alert title, up to 512 characters | -| alert_key | No | string | Alert identifier for updating or recovering existing alerts. Up to 255 characters; auto-generated if not specified | -| description | No | string | Alert description, up to 2048 characters | -| labels | No | map | Alert label collection in key-value format. Up to 50 labels | +Field|Required|Type|Description +:-:|:-:|:-:|:--- +event_status | Yes | string | Alert status. Enum (capitalized): `Critical`, `Warning`, `Info`, `Ok` (recovery) +title_rule | Yes | string | Alert title, up to 512 characters +alert_key | No | string | Alert identifier for updating or recovering existing alerts. Up to 255 characters; auto-generated if not specified +description | No | string | Alert description, up to 2048 characters +labels | No | map | Alert label collection in key-value format. Up to 50 labels - -A maximum of 100 events are processed per page, and up to 2000 events in total across all pages per pull. Excess events are truncated and recorded in the pull history. - +> A maximum of 100 events are processed per page, and up to 2000 events in total across all pages per pull. Excess events are truncated and recorded in the pull history. -## Template variables +
- +## III. Template Variables +--- + +
URL and Body support Go `text/template` syntax. The following variables are available to dynamically generate request content: @@ -134,9 +174,12 @@ Using ISO-formatted time in the Body: } ``` -## Pagination configuration +
+ +## IV. Pagination Configuration +--- - +
If your endpoint cannot return all data in a single response, you can configure cursor-based pagination. @@ -148,27 +191,14 @@ If your endpoint cannot return all data in a single response, you can configure | **param_name** | Pagination parameter name, e.g., `cursor` or `page_token` | | **inject_to** | Where to inject the pagination parameter: `query` (append to URL query string) or `body` (merge into request body JSON) | -### Pagination workflow +### Pagination Workflow - - -Flashduty sends the first request without pagination parameters. - +1. Flashduty sends the first request without pagination parameters +2. The next-page cursor value is extracted from the response JSON using `next_value_path` +3. The cursor value is injected into the next request using `param_name` as the key, either in the query string or the body +4. Pagination stops when `next_value_path` returns no value, the response contains an empty array, or the `max_pages` limit is reached - -The next-page cursor value is extracted from the response JSON using `next_value_path`. - - - -The cursor value is injected into the next request using `param_name` as the key, either in the query string or the body. - - - -Pagination stops when `next_value_path` returns no value, the response contains an empty array, or the `max_pages` limit is reached. - - - -### Pagination response example +### Pagination Response Example ```json { @@ -183,35 +213,13 @@ Pagination stops when `next_value_path` returns no value, the response contains With `next_value_path` set to `pagination.next_cursor`, the system will automatically use `eyJpZCI6MTAwfQ==` as the parameter value for the next page request. -## FAQ - - - -For security reasons, Flashduty (non-private deployment) does not allow access to private network addresses (e.g., `127.0.0.1`, `10.x.x.x`, `192.168.x.x`). Ensure your endpoint is accessible from the public internet. - -This restriction does not apply to private deployment versions. - - - -In the integration details page under **Pull History**, you can view the results of each pull execution, including status, number of events pulled, error messages, and more. - - - -Check the following: +
-1. Confirm the JSON response contains an `items` array and it is not empty. -2. Confirm each event has `event_status` and `title_rule` fields. -3. If you use `alert_key`, check whether the alert is a duplicate — events with identical status and content are deduplicated and discarded. -4. Check if any drop rules, inhibit rules, or silence rules are matching. - -For more information, see [Noise reduction](/en/on-call/channel/noise-reduction). - +## V. Severity Mapping +--- - -Yes. Click the manual trigger button on the integration details page. Manual triggers have a 60-second cooldown and cannot run concurrently with an ongoing scheduled pull. - +
- If your system uses custom severity identifiers (e.g., `P1`, `high`), you can configure mapping rules in the integration settings. For example: | Your value | Flashduty value | @@ -221,5 +229,45 @@ If your system uses custom severity identifiers (e.g., `P1`, `high`), you can co | P3 | Info | Values that do not match any mapping are processed as-is. - - + +
+ +## VI. FAQ +--- + +
+ Pull failed with a URL access denied error? + + For security reasons, Flashduty (non-private deployment) does not allow access to private network addresses (e.g., `127.0.0.1`, `10.x.x.x`, `192.168.x.x`). Ensure your endpoint is accessible from the public internet. + + This restriction does not apply to private deployment versions. + +
+ +
+ How do I view pull history and error details? + + In the integration details page under **Pull History**, you can view the results of each pull execution, including status, number of events pulled, error messages, and more. + +
+ +
+ Pull succeeds but no new alerts are generated? + + Check the following: + + 1. Confirm the JSON response contains an `items` array and it is not empty. + 2. Confirm each event has `event_status` and `title_rule` fields. + 3. If you use `alert_key`, check whether the alert is a duplicate — events with identical status and content are deduplicated and discarded. + 4. Check if any drop rules, inhibit rules, or silence rules are matching. + + For more information, see [Noise reduction](/en/on-call/channel/noise-reduction). + +
+ +
+ Can I manually trigger a pull? + + Yes. Click the manual trigger button on the integration details page. Manual triggers have a 60-second cooldown and cannot run concurrently with an ongoing scheduled pull. + +
diff --git "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.60 Http Pull \345\221\212\350\255\246\351\233\206\346\210\220.md" "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.60 Http Pull \345\221\212\350\255\246\351\233\206\346\210\220.md" index 46c4ad9c..06dfbb59 100644 --- "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.60 Http Pull \345\221\212\350\255\246\351\233\206\346\210\220.md" +++ "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.1 \345\221\212\350\255\246\351\233\206\346\210\220/8.1.60 Http Pull \345\221\212\350\255\246\351\233\206\346\210\220.md" @@ -1,28 +1,80 @@ --- title: "HTTP Pull 告警集成" description: "通过定时拉取外部 HTTP 接口的方式接入告警事件，适用于无法主动推送告警的系统。" +date: "2025-05-22T10:00:00+08:00" +url: "https://docs.flashcat.cloud/zh/flashduty/http-pull-integration-guide" --- -**版本要求**：HTTP Pull 集成需要 On-call 专业版及以上订阅。 +通过定时拉取外部 HTTP 接口的方式接入告警事件，适用于无法主动推送告警的系统。 + +
+ +## 在 Flashduty +--- +您可通过以下2种方式，获取一个集成推送地址，任选其一即可。 + +### 使用专属集成 + +当您不需要将告警事件路由到不同的协作空间，优先选择此方式，更简单。 + +
+ 展开 + + 1. 进入 Flashduty 控制台，选择 **协作空间**，进入某个空间的详情页面 + 2. 选择 **集成数据** tab，点击 **添加一个集成**，进入添加集成页面 + 3. 选择 **HTTP Pull** 集成，点击 **保存**，生成卡片。 + 4. 点击生成的卡片，可以查看到 **推送地址**，复制备用，完成。 + +
+ +### 使用共享集成 + +当您需要根据告警事件的 Payload 信息，将告警路由到不同的协作空间，优先选择此方式。 + +
+ 展开 + + 1. 进入 Flashduty 控制台，选择 **集成中心=>告警事件**，进入集成选择页面。 + 2. 选择 **HTTP Pull** 集成： + - **集成名称**：为当前集成定义一个名称。 + 3. 配置默认路由，并选择对应的协作空间（集成创建后可以前往 `路由` 进行更多路由规则的配置）。 + 4. 点击 **保存** 后，复制当前页面的新生成的 **推送地址** 备用。 + 5. 完成。 + +
+
+ +## 概述 +--- + +
Flashduty 支持两种告警接入模式：**推送（Push）** 和 **拉取（Pull）**。大多数集成使用推送模式，由外部监控系统主动将告警发送到 Flashduty。但部分系统不支持 Webhook 推送，或者告警数据只能通过 API 查询获取。 HTTP Pull 集成正是为这类场景设计的——您只需提供一个返回 JSON 格式告警数据的 HTTP 接口，Flashduty 会按照您设定的周期定时拉取，并将拉取到的数据转换为标准告警事件进行处理。 -## 适用场景 +### 适用场景 - 监控系统仅提供查询 API，不支持 Webhook 推送 - 告警数据存储在数据库或对象存储中，需要通过 HTTP 接口查询 - 自研系统暂时无法改造为推送模式，希望先通过拉取方式快速接入 -## 配置步骤 +### 配置步骤 + +1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**，搜索并选择 **HTTP Pull** 集成 +2. 配置请求参数（详见 [请求参数](#请求参数)） +3. 设置 **拉取周期（cycle_seconds）**，即多久拉取一次数据。最小值为 30 秒，默认 300 秒（5 分钟） +4. 按需配置严重程度映射（详见 [严重程度映射](#严重程度映射)） +5. 如果您的接口支持分页，可以配置分页参数以获取完整数据（详见 [分页配置](#分页配置)） +6. 点击 **保存** 启用集成。您也可以在集成详情页手动触发一次拉取 - - -进入 Flashduty 控制台，选择 **集成中心 → 告警事件**，搜索并选择 **HTTP Pull** 集成。 - +
+ +## 一、请求参数 +--- + +
- 配置 Flashduty 向您的接口发起请求时的参数： | 配置项 | 必填 | 说明 | @@ -34,30 +86,12 @@ HTTP Pull 集成正是为这类场景设计的——您只需提供一个返回 | **Timeout** | 否 | 单次请求超时时间，范围 1-10 秒，默认 5 秒 | | **RetryCount** | 否 | 请求失败时的重试次数，范围 0-2 次，默认 1 次 | - - - -设置 **拉取周期（cycle_seconds）**，即多久拉取一次数据。最小值为 30 秒，默认 300 秒（5 分钟）。 - - - -如果您的接口返回的告警严重程度与 Flashduty 的标准不一致，可以通过 **severity_mapping** 进行映射。 - -例如您的系统使用 `high` / `medium` / `low`，可映射为 Flashduty 的 `Critical` / `Warning` / `Info`。 - +
- -如果您的接口支持分页，可以配置分页参数以获取完整数据。详见 [分页配置](#分页配置)。 - - - -保存配置后，集成将按照设定的周期自动拉取数据。您也可以在集成详情页手动触发一次拉取。 - - - -## 响应格式要求 +## 二、响应格式要求 +--- - +
您的 HTTP 接口必须满足以下要求： @@ -91,21 +125,22 @@ HTTP Pull 集成正是为这类场景设计的——您只需提供一个返回 ### 事件字段说明 -| 字段 | 必含 | 类型 | 说明 | -| :--- | :--- | :--- | :--- | -| event_status | 是 | string | 告警状态。枚举值（首字母大写）：`Critical`、`Warning`、`Info`、`Ok`（恢复） | -| title_rule | 是 | string | 告警标题，不超过 512 字符 | -| alert_key | 否 | string | 告警标识，用于更新或恢复已有告警。不超过 255 字符，不指定时系统自动生成 | -| description | 否 | string | 告警描述，不超过 2048 字符 | -| labels | 否 | map | 告警标签集合，Key-Value 格式。至多 50 个标签 | +字段|必含|类型|说明 +:-:|:-:|:-:|:--- +event_status | 是 | string | 告警状态。枚举值（首字母大写）：`Critical`、`Warning`、`Info`、`Ok`（恢复） +title_rule | 是 | string | 告警标题，不超过 512 字符 +alert_key | 否 | string | 告警标识，用于更新或恢复已有告警。不超过 255 字符，不指定时系统自动生成 +description | 否 | string | 告警描述，不超过 2048 字符 +labels | 否 | map | 告警标签集合，Key-Value 格式。至多 50 个标签 - -单页最多处理 100 条事件，单次拉取全部分页累计最多处理 2000 条事件。超出的事件会被截断并记录在拉取历史中。 - +> 单页最多处理 100 条事件，单次拉取全部分页累计最多处理 2000 条事件。超出的事件会被截断并记录在拉取历史中。 -## 模板变量 +
- +## 三、模板变量 +--- + +
URL 和 Body 支持 Go `text/template` 语法，可使用以下变量动态生成请求内容： @@ -134,9 +169,12 @@ Body 中使用 ISO 格式时间： } ``` -## 分页配置 +
- +## 四、分页配置 +--- + +
如果您的接口一次返回不了全部数据，可以配置基于游标的分页。 @@ -150,23 +188,10 @@ Body 中使用 ISO 格式时间： ### 分页工作流程 - - -Flashduty 发起第一次请求（不含分页参数）。 - - - -从响应 JSON 中，按 `next_value_path` 提取下一页的游标值。 - - - -将游标值以 `param_name` 为键注入到下一次请求的 Query String 或 Body 中。 - - - -当 `next_value_path` 提取不到值、返回空数组、或达到 `max_pages` 上限时，停止分页。 - - +1. Flashduty 发起第一次请求（不含分页参数） +2. 从响应 JSON 中，按 `next_value_path` 提取下一页的游标值 +3. 将游标值以 `param_name` 为键注入到下一次请求的 Query String 或 Body 中 +4. 当 `next_value_path` 提取不到值、返回空数组、或达到 `max_pages` 上限时，停止分页 ### 分页响应示例 @@ -183,35 +208,13 @@ Flashduty 发起第一次请求（不含分页参数）。 对应配置 `next_value_path` 为 `pagination.next_cursor`，系统会自动将 `eyJpZCI6MTAwfQ==` 作为下一页请求的参数值。 -## 常见问题 - - - -出于安全考虑，Flashduty（非私有化部署）不允许访问内网地址（如 `127.0.0.1`、`10.x.x.x`、`192.168.x.x` 等）。请确保您的接口地址可以从公网访问。 +
-如果您使用私有化部署版本，此限制不适用。 - - - -在集成详情页的 **拉取历史** 中，可以查看每次拉取的执行结果，包括状态、拉取的事件数量、错误信息等。 - - - -请检查以下几点： - -1. 确认接口返回的 JSON 中包含 `items` 数组，且数组不为空。 -2. 确认每条事件都有 `event_status` 和 `title_rule` 字段。 -3. 如果使用了 `alert_key`，检查是否与之前的告警重复——状态和内容完全相同的事件会被去重丢弃。 -4. 检查是否匹配到了排除、抑制或静默规则。 - -更多内容请参考 [告警降噪](/zh/on-call/channel/noise-reduction)。 - +## 五、严重程度映射 +--- - -支持。在集成详情页点击手动触发按钮即可。手动触发有 60 秒的冷却时间，且不能与正在进行的定时拉取同时执行。 - +
- 如果您的系统使用自定义的严重程度标识（如 `P1`、`high`），可以在集成配置中设置映射关系。例如： | 您的值 | Flashduty 值 | @@ -221,5 +224,45 @@ Flashduty 发起第一次请求（不含分页参数）。 | P3 | Info | 未匹配到映射的值将保持原样处理。 - - + +
+ +## 六、常见问题 +--- + +
+ 拉取失败，提示 URL 不允许访问？ + + 出于安全考虑，Flashduty（非私有化部署）不允许访问内网地址（如 `127.0.0.1`、`10.x.x.x`、`192.168.x.x` 等）。请确保您的接口地址可以从公网访问。 + + 如果您使用私有化部署版本，此限制不适用。 + +
+ +
+ 如何查看拉取历史和错误详情？ + + 在集成详情页的 **拉取历史** 中，可以查看每次拉取的执行结果，包括状态、拉取的事件数量、错误信息等。 + +
+ +
+ 拉取正常但没有产生新告警？ + + 请检查以下几点： + + 1. 确认接口返回的 JSON 中包含 `items` 数组，且数组不为空。 + 2. 确认每条事件都有 `event_status` 和 `title_rule` 字段。 + 3. 如果使用了 `alert_key`，检查是否与之前的告警重复——状态和内容完全相同的事件会被去重丢弃。 + 4. 检查是否匹配到了排除、抑制或静默规则。 + + 更多内容请参考 [告警降噪](/zh/on-call/channel/noise-reduction)。 + +
+ +
+ 支持手动触发拉取吗？ + + 支持。在集成详情页点击手动触发按钮即可。手动触发有 60 秒的冷却时间，且不能与正在进行的定时拉取同时执行。 + +