diff --git a/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.0 Standard Alert Integration.md b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.0 Standard Alert Integration.md index 01902c17..62545593 100644 --- a/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.0 Standard Alert Integration.md +++ b/flashduty/en/1. On-call/8. Integrations/8.1 Alerts integration/8.1.0 Standard Alert Integration.md @@ -177,7 +177,96 @@ Failed Response: } ``` -## III. Best Practices +## III. Field Mapping and Value Mapping +--- + +If your system's JSON format cannot directly match the standard Payload structure above, you can configure **field mapping** and **value mapping** in the integration settings to let Flashduty automatically convert any JSON format into standard alert events. + +###### Once field mapping is configured, the request body no longer requires a fixed format. It accepts any JSON object, and also supports batch push via JSON arrays (up to 100 items per request). + + +### Field mapping + +Use `{{variable.path}}` syntax to reference fields from the original JSON and map them to target fields of the standard alert event. + +Supported target fields: + +| Target field | Description | +| :--- | :--- | +| title | Alert title | +| title_rule | Alert title rule | +| description | Alert description | +| event_status | Alert status (Critical / Warning / Info / Ok) | +| alert_key | Alert identifier | +| labels | Alert labels | +| images | Image array | + +**Variable syntax:** + +- Use `.` to separate path levels, e.g. `{{data.severity}}` references a nested field +- When the entire value is a single variable (e.g. `"{{tags}}"`), the original data type is preserved (object, array, etc.) +- When a variable is mixed with other text (e.g. `"{{host}} - {{check}}"`), variables are converted to strings for concatenation + +**Two ways to map labels:** + +- **Wildcard expansion**: `"labels": "{{tags}}"` — expands all children of the `tags` object as labels +- **Per-label mapping**: `"labels": {"env": "{{tags.env}}", "host": "{{hostname}}"}` — maps each label individually + +**Example:** + +Your system pushes the following format: + +```json +{ + "alert_name": "CPU usage high", + "status": "firing", + "severity": "high", + "host": "web-01", + "tags": { + "env": "production", + "service": "api" + } +} +``` + +Configure the following field mapping: + +```json +{ + "title_rule": "{{alert_name}}", + "event_status": "{{severity}}", + "alert_key": "{{host}}::{{alert_name}}", + "description": "Host {{host}} alert: {{alert_name}}", + "labels": "{{tags}}" +} +``` + +### Value mapping + +When your source system's field values differ from Flashduty's standard (e.g. using `high` instead of `Critical` for severity), configure value mapping for automatic conversion. + +Value mapping is configured per **field path**, with each path containing a `source value → target value` mapping table. + +**Example:** + +```json +{ + "severity": { + "high": "Critical", + "medium": "Warning", + "low": "Info", + "resolved": "Ok" + } +} +``` + +Combined with the field mapping above, `"severity": "high"` in the original JSON is first extracted via field mapping, then converted to `Critical` via value mapping, and finally written to the `event_status` field. + + +###### Warning: All `{{...}}` variables must resolve to a value in the original JSON, otherwise the request will fail. It is recommended to test your mapping configuration with a small dataset first. + + +## IV. Best Practices --- 1. Send events to Flashduty when alert status changes @@ -187,7 +276,7 @@ Failed Response: - Alert ownership information, like team, owner - Alert category information, like class (api, db, net) -## IV. FAQ +## V. FAQ ---
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 8c210b84..5a849edc 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 @@ -88,8 +88,8 @@ Configure the parameters Flashduty uses when making requests to your endpoint: | **Method** | No | Request method, `GET` or `POST`. Defaults to `GET`. Body cannot be set when using GET | | **Headers** | No | Custom request headers in key-value format. For security reasons, sensitive headers such as `Authorization` and `Cookie` are not allowed | | **Body** | No | Request body, only available for POST. Supports [template variables](#template-variables) and must be valid JSON | -| **Timeout** | No | Per-request timeout, 1–10 seconds. Defaults to 5 seconds | -| **RetryCount** | No | Number of retries on failure, 0–2. Defaults to 1 | +| **Timeout** | No | Per-request timeout, 1–300 seconds. Defaults to 10 seconds | +| **RetryCount** | No | Number of retries on failure, 0–10. Defaults to 0 | @@ -155,7 +155,8 @@ URL and Body support Go `text/template` syntax. The following variables are avai | `{{.NowTime}}` | int64 | Current time (Unix timestamp in seconds) | | `{{.LastPullTimeISO}}` | string | Last pull time (ISO 8601 format, e.g., `2026-05-13T06:00:00Z`) | | `{{.NowTimeISO}}` | string | Current time (ISO 8601 format) | -| `{{.CursorValue}}` | string | Pagination cursor value, empty for the first page | +| `{{.CursorValue}}` | string | Pagination cursor value, empty for the first page. Equivalent to `{{.PageValue}}` | +|| `{{.PageValue}}` | string | Alias for the pagination cursor value, equivalent to `{{.CursorValue}}`. Empty string on the first request; subsequent requests use the value extracted from the previous response via the cursor path | ### Examples @@ -232,7 +233,18 @@ Values that do not match any mapping are processed as-is. -## VI. FAQ +## VI. Default Route +--- + +
+ +When creating a "Shared Integration" (under **Integration Center => Alert Events**), you must configure a default route — otherwise newly pulled events will be dropped. After creation, you can add finer-grained rules under **Route**. + +A "Dedicated Integration" (created under the **Integrations** tab of a specific channel) is automatically bound to that channel and does not need a separate default route. + +
+ +## VII. FAQ ---
@@ -261,7 +273,6 @@ Values that do not match any mapping are processed as-is. 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).
diff --git a/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.2 Incident webhook.md b/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.2 Incident webhook.md index c9621352..a731cc85 100644 --- a/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.2 Incident webhook.md +++ b/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.2 Incident webhook.md @@ -188,7 +188,84 @@ curl -X POST 'https://example.com/incident/webhook?a=a' \ }' -v ``` -## III. FAQ +## III. Custom Request Body and Value Mapping + +### Custom request body + +By default, the system pushes the complete JSON data following the Payload structure described above. If your receiver requires a specific data format, you can use a **custom request body** to reorganize the push content. + +Use `{{field.path}}` syntax to reference any field from the default Payload. The system replaces variables with actual values at push time. + +**Variable syntax:** + +- Use `.` to separate path levels, e.g. `{{incident.title}}` references the incident title +- Array index access is supported, e.g. `{{incident.responders.0.email}}` references the first responder's email +- When the entire value is a single variable (e.g. `"{{incident.labels}}"`), the original data type is preserved (object, array, number, etc.) +- When a variable is mixed with other text (e.g. `"Incident: {{incident.title}}"`), the variable is converted to a string for concatenation + +**Example:** + +Transform the default Payload into a custom format for an internal system: + +```json +{ + "msg_type": "incident", + "event": "{{event_type}}", + "content": { + "id": "{{incident.incident_id}}", + "name": "{{incident.title}}", + "severity": "{{incident.incident_severity}}", + "status": "{{incident.progress}}", + "channel": "{{incident.channel_name}}", + "url": "{{incident.detail_url}}", + "labels": "{{incident.labels}}", + "responders": "{{incident.responders}}" + } +} +``` + +:::tips +If a variable path does not exist in the default Payload, the system keeps the original `{{...}}` text without replacement. It is recommended to first check the actual default Payload via invocation history to confirm available field paths. +::: + +### Value mapping + +In the custom request body, you may need to convert Flashduty field values to the format expected by the receiving system. **Value mapping** automatically transforms values during variable resolution. + +Value mapping is configured per **field path**, with each path containing a `source value → target value` mapping table. + +**Example:** + +Convert severity and progress to custom values for the receiving system: + +```json +{ + "incident.incident_severity": { + "Critical": "P0", + "Warning": "P1", + "Info": "P2" + }, + "incident.progress": { + "Triggered": "open", + "Processing": "in_progress", + "Closed": "resolved" + } +} +``` + +Used with the following custom request body: + +```json +{ + "severity": "{{incident.incident_severity}}", + "status": "{{incident.progress}}", + "title": "{{incident.title}}" +} +``` + +When the incident severity is `Critical`, the `severity` field in the push result will be `P0`. Values that do not match any mapping are sent as-is. + +## IV. FAQ 1. **Is there a response timeout for the service?** diff --git a/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.3 Custom action.md b/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.3 Custom action.md index e9e2836d..902a5d28 100644 --- a/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.3 Custom action.md +++ b/flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.3 Custom action.md @@ -222,7 +222,58 @@ curl -X POST 'https://example.com/incident/action?a=a' \ }' -v ``` -## III. Use Cases +## III. Custom Request Body and Value Mapping + +### Custom request body + +By default, the system pushes the complete JSON data following the Payload structure described above. If your receiver requires a specific data format, you can use a **custom request body** to reorganize the push content. + +Use `{{field.path}}` syntax to reference any field from the default Payload. The system replaces variables with actual values at push time. + +**Variable syntax:** + +- Use `.` to separate path levels, e.g. `{{incident.title}}` references the incident title +- Array index access is supported, e.g. `{{incident.responders.0.email}}` references the first responder's email +- When the entire value is a single variable (e.g. `"{{incident.labels}}"`), the original data type is preserved (object, array, number, etc.) +- When a variable is mixed with other text (e.g. `"Incident: {{incident.title}}"`), the variable is converted to a string for concatenation + +**Example:** + +```json +{ + "action": "{{event_type}}", + "incident_id": "{{incident.incident_id}}", + "title": "{{incident.title}}", + "severity": "{{incident.incident_severity}}", + "url": "{{incident.detail_url}}", + "operator": "{{person.person_name}}", + "labels": "{{incident.labels}}" +} +``` + +:::tips +If a variable path does not exist in the default Payload, the system keeps the original `{{...}}` text without replacement. It is recommended to first check the actual default Payload via a test push to confirm available field paths. +::: + +### Value mapping + +Value mapping automatically transforms field values during variable resolution in the custom request body. Value mapping is configured per **field path**. + +**Example:** + +```json +{ + "incident.incident_severity": { + "Critical": "P0", + "Warning": "P1", + "Info": "P2" + } +} +``` + +Used with `"severity": "{{incident.incident_severity}}"` in the custom request body, when the incident severity is `Critical`, the `severity` field in the push result will be `P0`. Values that do not match any mapping are sent as-is. + +## IV. Use Cases ### Host Restart 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.0 \346\240\207\345\207\206\345\221\212\350\255\246\344\272\213\344\273\266\351\233\206\346\210\220\346\214\207\345\274\225.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.0 \346\240\207\345\207\206\345\221\212\350\255\246\344\272\213\344\273\266\351\233\206\346\210\220\346\214\207\345\274\225.md" index b6d1092f..5ed2414c 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.0 \346\240\207\345\207\206\345\221\212\350\255\246\344\272\213\344\273\266\351\233\206\346\210\220\346\214\207\345\274\225.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.0 \346\240\207\345\207\206\345\221\212\350\255\246\344\272\213\344\273\266\351\233\206\346\210\220\346\214\207\345\274\225.md" @@ -183,7 +183,97 @@ curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_ } ``` -## 三、最佳实践 +## 三、字段映射与值映射 +--- + +如果您的系统推送的 JSON 格式无法直接匹配上述标准 Payload 结构，可以在集成设置中配置 **字段映射** 和 **值映射**，让 Flashduty 自动将任意格式的 JSON 转换为标准告警事件。 + + +###### 配置字段映射后，请求体不再要求固定格式，可以接收任意 JSON 对象，也支持 JSON 数组批量推送（单次最多 100 条）。 + + +### 字段映射 + +使用 `{{变量路径}}` 语法引用原始 JSON 中的字段，将其映射到标准告警事件的目标字段。 + +支持的目标字段： + +| 目标字段 | 说明 | +| :--- | :--- | +| title | 告警标题 | +| title_rule | 告警标题规则 | +| description | 告警描述 | +| event_status | 告警状态（Critical / Warning / Info / Ok） | +| alert_key | 告警标识 | +| labels | 告警标签 | +| images | 图片数组 | + +**变量语法：** + +- 用 `.` 分隔路径层级，如 `{{data.severity}}` 引用嵌套字段 +- 当整个值只有一个变量时（如 `"{{tags}}"`），会保留原始数据类型（对象、数组等） +- 当变量与其他文本混合时（如 `"{{host}} - {{check}}"`），变量会被转为字符串拼接 + +**labels 的两种映射方式：** + +- **通配符展开**：`"labels": "{{tags}}"` — 将 `tags` 对象的所有子字段展开为标签 +- **逐个映射**：`"labels": {"env": "{{tags.env}}", "host": "{{hostname}}"}` — 每个标签单独映射 + +**示例：** + +您的系统推送格式如下： + +```json +{ + "alert_name": "CPU usage high", + "status": "firing", + "severity": "high", + "host": "web-01", + "tags": { + "env": "production", + "service": "api" + } +} +``` + +配置如下字段映射： + +```json +{ + "title_rule": "{{alert_name}}", + "event_status": "{{severity}}", + "alert_key": "{{host}}::{{alert_name}}", + "description": "Host {{host}} alert: {{alert_name}}", + "labels": "{{tags}}" +} +``` + +### 值映射 + +当源系统的字段值与 Flashduty 标准不一致时（如严重程度使用 `high` 而非 `Critical`），可以配置值映射进行自动转换。 + +值映射按**字段路径**分组配置，每个路径下是一个 `源值 → 目标值` 的映射表。 + +**示例：** + +```json +{ + "severity": { + "high": "Critical", + "medium": "Warning", + "low": "Info", + "resolved": "Ok" + } +} +``` + +配合上面的字段映射，原始 JSON 中的 `"severity": "high"` 会先通过字段映射提取，再通过值映射转换为 `Critical`，最终写入 `event_status` 字段。 + + +###### 注意：所有 `{{...}}` 变量必须能在原始 JSON 中解析到值，否则请求会报错。建议先用少量数据测试映射配置是否正确。 + + +## 四、最佳实践 --- 1. 当告警状态发生变更时，向 Flashduty发送事件 @@ -194,7 +284,7 @@ curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_ - 告警的类别信息，如 class（api，db，net） -## 四、常见问题 +## 五、常见问题 ---
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 816ca89f..8236f2a0 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" @@ -83,8 +83,8 @@ HTTP Pull 集成正是为这类场景设计的——您只需提供一个返回 | **Method** | 否 | 请求方法，支持 `GET` 和 `POST`，默认 `GET`。使用 GET 时不可设置 Body | | **Headers** | 否 | 自定义请求头，Key-Value 格式。出于安全考虑，`Authorization`、`Cookie` 等敏感 Header 不可使用 | | **Body** | 否 | 请求体，仅 POST 方法可用。支持 [模板变量](#模板变量)，需为合法的 JSON 格式 | -| **Timeout** | 否 | 单次请求超时时间，范围 1-10 秒，默认 5 秒 | -| **RetryCount** | 否 | 请求失败时的重试次数，范围 0-2 次，默认 1 次 | +| **Timeout** | 否 | 单次请求超时时间，范围 1-300 秒，默认 10 秒 | +| **RetryCount** | 否 | 请求失败时的重试次数，范围 0-10 次，默认 0 次 | @@ -150,7 +150,8 @@ URL 和 Body 支持 Go `text/template` 语法，可使用以下变量动态生 | `{{.NowTime}}` | int64 | 当前时间（Unix 秒级时间戳） | | `{{.LastPullTimeISO}}` | string | 上次拉取时间（ISO 8601 格式，如 `2026-05-13T06:00:00Z`） | | `{{.NowTimeISO}}` | string | 当前时间（ISO 8601 格式） | -| `{{.CursorValue}}` | string | 分页游标值，首页为空 | +| `{{.CursorValue}}` | string | 分页游标值，首页为空。等价于 `{{.PageValue}}` | +|| `{{.PageValue}}` | string | 分页游标值，与 `{{.CursorValue}}` 等价。首次请求时为空字符串，后续请求使用上一次响应中按游标路径提取的值 | ### 使用示例 @@ -227,7 +228,18 @@ Body 中使用 ISO 格式时间： -## 六、常见问题 +## 六、默认路由 +--- + +
+ +新增「共享集成」（即在 **集成中心 ⇒ 告警事件** 中创建）时，必须配置默认路由，否则新拉取到的事件将被丢弃。集成创建后可在 **路由** 中追加更细粒度的规则。 + +「专属集成」（在某个协作空间的 **集成数据** 中创建）会自动绑定到所在空间，不需要单独配置默认路由。 + +
+ +## 七、常见问题 ---
@@ -249,7 +261,5 @@ Body 中使用 ISO 格式时间： 3. 如果使用了 `alert_key`，检查是否与之前的告警重复——状态和内容完全相同的事件会被去重丢弃。 4. 检查是否匹配到了排除、抑制或静默规则。 - 更多内容请参考 [告警降噪](/zh/on-call/channel/noise-reduction)。 -
diff --git "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.2 \346\225\205\351\232\234 webhook.md" "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.2 \346\225\205\351\232\234 webhook.md" index 582ce6be..27e1668a 100644 --- "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.2 \346\225\205\351\232\234 webhook.md" +++ "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.2 \346\225\205\351\232\234 webhook.md" @@ -189,7 +189,84 @@ curl -X POST 'https://example.com/incident/webhook?a=a' \ }' -v ``` -## 三、常见问题 +## 三、自定义请求体与值映射 + +### 自定义请求体 + +默认情况下，系统会按照上述 Payload 结构推送完整的 JSON 数据。如果您的接收方对数据格式有特殊要求，可以通过**自定义请求体**来重新组织推送内容。 + +使用 `{{字段路径}}` 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 + +**变量语法：** + +- 用 `.` 分隔路径层级，如 `{{incident.title}}` 引用故障标题 +- 支持数组索引访问，如 `{{incident.responders.0.email}}` 引用第一个处理人的邮箱 +- 当整个值只有一个变量时（如 `"{{incident.labels}}"`），会保留原始数据类型（对象、数组、数字等） +- 当变量与其他文本混合时（如 `"故障：{{incident.title}}"`），变量会被转为字符串拼接 + +**示例：** + +将默认 Payload 转为自定义格式推送到企业内部系统： + +```json +{ + "msg_type": "incident", + "event": "{{event_type}}", + "content": { + "id": "{{incident.incident_id}}", + "name": "{{incident.title}}", + "severity": "{{incident.incident_severity}}", + "status": "{{incident.progress}}", + "channel": "{{incident.channel_name}}", + "url": "{{incident.detail_url}}", + "labels": "{{incident.labels}}", + "responders": "{{incident.responders}}" + } +} +``` + +:::tips +如果变量路径在默认 Payload 中不存在，系统会保留原始的 `{{...}}` 文本不做替换。建议先通过调用历史查看实际推送的默认 Payload，确认可用的字段路径。 +::: + +### 值映射 + +在自定义请求体中，您可能需要将 Flashduty 的字段值转换为接收方系统所期望的格式。通过 **值映射** 可以在变量解析时自动完成值的转换。 + +值映射按**字段路径**分组配置，每个路径下是一个 `源值 → 目标值` 的映射表。 + +**示例：** + +将严重程度和处理进度转换为接收方系统的自定义值： + +```json +{ + "incident.incident_severity": { + "Critical": "P0", + "Warning": "P1", + "Info": "P2" + }, + "incident.progress": { + "Triggered": "open", + "Processing": "in_progress", + "Closed": "resolved" + } +} +``` + +配合如下自定义请求体使用： + +```json +{ + "severity": "{{incident.incident_severity}}", + "status": "{{incident.progress}}", + "title": "{{incident.title}}" +} +``` + +当故障严重程度为 `Critical` 时，推送结果中 `severity` 字段的值为 `P0`。未匹配到映射的值将保持原样。 + +## 四、常见问题 1. **服务是否有响应超时时间？** diff --git "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.3 \350\207\252\345\256\232\344\271\211\346\223\215\344\275\234.md" "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.3 \350\207\252\345\256\232\344\271\211\346\223\215\344\275\234.md" index 429dc760..6c8fe758 100644 --- "a/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.3 \350\207\252\345\256\232\344\271\211\346\223\215\344\275\234.md" +++ "b/flashduty/zh/1. On-call/5. \351\233\206\346\210\220\345\274\225\345\257\274/8.5 Webhooks/8.5.3 \350\207\252\345\256\232\344\271\211\346\223\215\344\275\234.md" @@ -230,7 +230,58 @@ curl -X POST 'https://example.com/incident/action?a=a' \ }' -v ``` -## 三、使用场景 +## 三、自定义请求体与值映射 + +### 自定义请求体 + +默认情况下，系统会按照上述 Payload 结构推送完整的 JSON 数据。如果您的接收方对数据格式有特殊要求，可以通过**自定义请求体**来重新组织推送内容。 + +使用 `{{字段路径}}` 语法引用默认 Payload 中的任意字段，系统会在推送时将变量替换为实际值。 + +**变量语法：** + +- 用 `.` 分隔路径层级，如 `{{incident.title}}` 引用故障标题 +- 支持数组索引访问，如 `{{incident.responders.0.email}}` 引用第一个处理人的邮箱 +- 当整个值只有一个变量时（如 `"{{incident.labels}}"`），会保留原始数据类型（对象、数组、数字等） +- 当变量与其他文本混合时（如 `"故障：{{incident.title}}"`），变量会被转为字符串拼接 + +**示例：** + +```json +{ + "action": "{{event_type}}", + "incident_id": "{{incident.incident_id}}", + "title": "{{incident.title}}", + "severity": "{{incident.incident_severity}}", + "url": "{{incident.detail_url}}", + "operator": "{{person.person_name}}", + "labels": "{{incident.labels}}" +} +``` + +:::tips +如果变量路径在默认 Payload 中不存在，系统会保留原始的 `{{...}}` 文本不做替换。建议先通过测试推送查看实际的默认 Payload，确认可用的字段路径。 +::: + +### 值映射 + +通过值映射，可以在自定义请求体的变量解析时自动转换字段值。值映射按**字段路径**分组配置。 + +**示例：** + +```json +{ + "incident.incident_severity": { + "Critical": "P0", + "Warning": "P1", + "Info": "P2" + } +} +``` + +配合自定义请求体中的 `"severity": "{{incident.incident_severity}}"` 使用，当故障严重程度为 `Critical` 时，推送结果中 `severity` 字段的值为 `P0`。未匹配到映射的值将保持原样。 + +## 四、使用场景 ### 重启主机 @@ -248,7 +299,7 @@ curl -X POST 'https://example.com/incident/action?a=a' \ 当确定故障影响到线上服务，可以触发外部 status page 更新，及时的通知到您的客户或上下游。 -## 四、常见问题 +## 五、常见问题 1. **服务是否有响应超时时间？**