> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt > Use this file to discover all available pages before exploring further. # 预览告警处理规则效果 > 用未保存的告警处理规则按接入的方式处理一个事件，返回处理前后的差异。 ## 限制说明 | 项目 | 说明 | | - | - | | 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** | | 权限要求 | **协作空间管理**（`on-call`）或 **集成中心查看**（`on-call`）或 **集成中心管理**（`on-call`） | ## 使用说明 * 不会保存任何内容，也不创建告警或事件。 * 该集成已存的标签增强规则会先执行，然后按顺序执行你传入的 `rules`，作用在增强后的事件上。 * 恢复（`Ok`）事件会直接关闭告警、不执行处理规则：`is_recovery` 为 `true`，每一步都是 `not_executed`，`detail` 为 `recovery_event`。 * `dropped`、`inhibited` 说明是哪类规则中断了事件：`alert_drop` 直接丢弃，`alert_inhibit` 在存在匹配的活跃源告警时丢弃。该规则之后的步骤为 `not_executed`。 * 没有规则命中时，`after` 是通知模板渲染后的事件，即在协作空间中会看到的内容。 ## OpenAPI ````yaml /api-reference/on-call.openapi.zh.json post /alert/pipeline/preview openapi: 3.1.0 info: title: Flashduty 开放 API description: >- Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。 version: 1.0.0 servers: - url: https://api.flashcat.cloud description: Flashduty Open API security: - AppKeyAuth: [] tags: - name: On-call/故障管理 description: '' - name: On-call/协作空间 description: '' - name: On-call/告警管理 description: 查询、查看和处理告警，管理卡片视图与告警处理规则。 - name: On-call/集成中心 description: '' - name: On-call/IM 集成 description: IM 集成相关查询，例如查看哪些集成开启了作战室。 - name: On-call/值班排班 description: '' - name: On-call/许可管理 description: '' - name: On-call/日历管理 description: '' - name: On-call/通知模板 description: '' - name: On-call/标签增强 description: 自定义字段、富化规则及数据映射（映射规则、映射数据、映射 API）管理。 - name: On-call/分析看板 description: '' - name: On-call/状态页 description: '' - name: On-call/变更管理 description: '' paths: /alert/pipeline/preview: post: tags: - On-call/告警管理 summary: 预览告警处理规则效果 description: 用未保存的告警处理规则按接入的方式处理一个事件，返回处理前后的差异。 operationId: alert-read-pipeline-preview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertPipelinePreviewRequest' example: integration_id: 6113996590131 rules: - kind: severity_reset if: - key: labels.env oper: IN vals: - test settings: severity: Info - kind: alert_drop if: - key: title oper: IN vals: - /.*noise.*/ settings: {} event: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. event_status: Warning labels: service: mysql env: prod host: db-3 responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/AlertPipelinePreviewResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: is_recovery: false before: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. severity: Warning labels: service: mysql env: prod host: db-3 after: title: Disk usage 95% on db-3 description: Root filesystem is 95% full on db-3. severity: Warning labels: service: mysql env: prod host: db-3 dropped: false inhibited: false steps: - index: 0 kind: severity_reset result: not_matched detail: condition_not_met - index: 1 kind: alert_drop result: not_matched detail: condition_not_met '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/ServerError' components: schemas: AlertPipelinePreviewRequest: type: object description: '`POST /alert/pipeline/preview` 的请求体。' required: - integration_id - event properties: integration_id: type: integer format: int64 minimum: 1 description: 预览所用的集成 ID；该集成已存的标签增强会先执行。 rules: type: array maxItems: 50 items: $ref: '#/components/schemas/AlertPipeline' description: 按顺序尝试的告警处理规则，最多 50 条；不会使用该集成已存的处理规则。 event: $ref: '#/components/schemas/AlertEvent' description: 要跑规则的事件。 SuccessEnvelope: type: object description: >- 成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。 properties: request_id: type: string description: 本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。 example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: description: 接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。 required: - request_id AlertPipelinePreviewResponse: type: object description: 告警处理预览的结果。 required: - is_recovery - before - after - dropped - inhibited - steps properties: is_recovery: type: boolean description: 事件是恢复事件时为 `true`：接入会直接关闭告警，不执行处理规则。 before: $ref: '#/components/schemas/AlertPipelinePreviewEvent' description: 事件进入时的样子。 after: $ref: '#/components/schemas/AlertPipelinePreviewEvent' description: 规则执行后、通知模板渲染出的事件。 dropped: type: boolean description: 某条规则丢弃了该事件、不会产生告警时为 `true`。 inhibited: type: boolean description: 某条规则因存在匹配的活跃源告警而抑制了该事件时为 `true`。 steps: type: array items: $ref: '#/components/schemas/PipelineStep' description: 每条规则一项，按执行顺序排列。 AlertPipeline: type: object description: 单条告警处理规则。 properties: kind: type: string enum: - title_reset - description_reset - severity_reset - alert_drop - alert_inhibit description: >- 规则类型。规则按数组顺序依次执行，`if` 条件命中后按 `kind` 处理事件。 | 值 | 含义 | |---|---| | `title_reset` | 按 `settings.title` 模板重写事件标题。 | | `description_reset` | 按 `settings.description` 模板重写事件描述。 | | `severity_reset` | 将事件严重程度与状态重置为 `settings.severity`（`Critical`/`Warning`/`Info`）。 | | `alert_drop` | 直接丢弃匹配的事件，不生成告警。 | | `alert_inhibit` | 当存在匹配 `settings.source_filters` 且按 `settings.equals` 关联的活跃源告警时，丢弃该事件（抑制）。 | if: type: - array - 'null' items: $ref: '#/components/schemas/FilterCondition' description: >- AND 过滤条件列表——事件满足全部条件时规则才生效。可用的 key：`severity`（别名 `alert_severity`、`event_severity`）、`status`、`title`、`title_rule`、`description`、`alert_key`、`integration_id`（别名 `data_source_id`）以及 `labels.<名称>`；其他 key 返回 `InvalidParameter`。为 `null` 或不传时规则作用于所有事件。 settings: type: object description: >- 与 `kind` 对应的配置。取值结构因 `kind` 而异： - `title_reset`：`{ "title": "<模板字符串>" }` - `description_reset`：`{ "description": "<模板字符串>" }` - `severity_reset`：`{ "severity": "Critical"|"Warning"|"Info" }` - `alert_drop`：`{}` (空对象) - `alert_inhibit`：`{ "equals": ["<标签键>", ...], "source_filters": }` oneOf: - $ref: '#/components/schemas/ApTitleReset' - $ref: '#/components/schemas/ApDescriptionReset' - $ref: '#/components/schemas/ApSeverityReset' - $ref: '#/components/schemas/ApAlertDrop' - $ref: '#/components/schemas/ApAlertInhibit' required: - kind AlertEvent: type: object description: 一条原始告警事件，与接入管道接收和存储的结构一致。 required: - event_status properties: title: type: string description: 事件标题。未提供 `title_rule` 时必填；两者共同决定告警标题的来源。 title_rule: type: string description: 标题模板，例如 `$service::$alertname`；`title` 为空时用它从 `labels` 生成标题。 description: type: string description: 事件描述，超过 2048 字符会被截断。 alert_key: type: string description: 用于将多个事件合并到同一告警的去重键。可为空：预览会随机生成一个键，因此不会发生合并。 event_status: type: string enum: - Critical - Warning - Info - Ok description: 事件状态。`Critical`、`Warning`、`Info` 为触发事件，`Ok` 为恢复事件。 event_severity: type: string enum: - Critical - Warning - Info description: 触发事件携带的严重级别。预览会在触发事件上用 `event_status` 覆盖它。 event_time: type: integer format: int64 description: Unix 时间戳（秒）。预览使用当前时间，传入值会被忽略。 labels: type: object additionalProperties: type: string description: 事件标签集合，最多 50 项；键为标签名，值为字符串。 images: type: array items: $ref: '#/components/schemas/AlertImage' description: 事件附带的图片。 AlertPipelinePreviewEvent: type: object description: 告警处理预览当时的事件。 required: - title - description - severity - labels properties: title: type: string description: 事件标题。 description: type: string description: 事件描述。 severity: type: string enum: - Critical - Warning - Info - Ok description: 此时事件携带的严重级别。 labels: type: object additionalProperties: type: string description: 标签集合。 PipelineStep: type: object description: 单条告警处理规则对事件做了什么。 required: - index - kind - result - detail properties: index: type: integer description: 规则在 `rules` 中的位置，从 0 开始。 kind: type: string enum: - title_reset - description_reset - severity_reset - alert_drop - alert_inhibit description: |- 执行过的规则类型。 | 取值 | 含义 | |---|---| | `title_reset` | 用规则模板改写标题。 | | `description_reset` | 用规则模板改写描述。 | | `severity_reset` | 把严重级别和状态重置为规则中的 `severity`。 | | `alert_drop` | 直接丢弃事件，不产生告警。 | | `alert_inhibit` | 存在匹配的活跃源告警时丢弃事件。 | result: type: string enum: - applied - not_matched - not_executed description: >- 规则结果：`applied`（改变了事件或终止了后续处理）、`not_matched`（`if` 条件没有全部满足）、`not_executed`（前面的规则已终止处理，或事件是恢复事件）。 detail: type: string description: >- 上述结果对应的 `condition_not_met`、`no_active_source_alert`、`inhibit_not_evaluated` 或 `recovery_event`；其他情况为结果值或错误信息。 ErrorResponse: type: object description: 错误响应结构。`error` 必填，`data` 不存在。 properties: request_id: type: string example: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 description: 本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。 error: $ref: '#/components/schemas/DutyError' required: - request_id - error FilterCondition: type: object required: - key - oper - vals properties: key: type: string description: >- 要匹配的字段。可用的内置字段取决于策略类型，见承载条件的字段说明；任意 `labels.`（如 `labels.env`）始终可用。未知字段返回 `InvalidParameter`。告警或故障缺少该字段时，`IN` 不匹配，`NOTIN` 匹配。 oper: type: string enum: - IN - NOTIN description: 匹配操作符，区分大小写。`IN`：字段值匹配 `vals` 中任意一项即命中；`NOTIN`：与 `vals` 中所有项都不匹配才命中。 vals: type: array items: type: string description: >- 要比较的值，至少一项。每项的匹配方式：普通字符串精确匹配；含 `*` 或 `?` 时按通配符匹配整个值；用斜杠包裹时按正则表达式匹配，如 `/^db-/`（可匹配值的任意位置）；`cidr:<网段>` 匹配 IP 范围，如 `cidr:203.0.113.0/24`；`num::<数字>` 做数值比较，`op` 为 `lt`、`le`、`gt`、`ge`，如 `num:gt:90`。 ApTitleReset: type: object description: '`title_reset` 的配置：按标题规则重写事件标题。' required: - title properties: title: type: string description: >- 标题规则。以 `[TPL]` 开头时按 Go 模板基于事件渲染，如 `[TPL]{{.Labels.service}}`；否则视为以 `::` 分隔的片段列表，`$名称` 片段替换为同名标签的值，其他片段原样保留。 ApDescriptionReset: type: object description: '`description_reset` 的配置：用渲染后的模板替换事件描述。' required: - description properties: description: type: string description: 描述模板。仅以 `[TPL]` 开头的值生效：其后内容按 Go 模板基于事件渲染并替换描述；不带该前缀时描述保持不变。 ApSeverityReset: type: object description: '`severity_reset` 的配置：把事件的严重程度和状态都设为固定值。' required: - severity properties: severity: type: string enum: - Critical - Warning - Info description: 要设置的严重程度：`Critical`、`Warning` 或 `Info`。事件状态会被设为相同的值。 ApAlertDrop: type: object description: '`alert_drop` 的配置：无字段，传 `{}` 即可。命中的事件会被丢弃，不会创建或更新告警。' properties: {} ApAlertInhibit: type: object description: >- `alert_inhibit` 的配置：当同一集成中存在一条活跃告警（`alert_key` 不同、在事件前 10 分钟内开始），且它满足 `source_filters`、在每个 `equals` key 上与当前事件取值相同时，当前事件被丢弃。 required: - equals - source_filters properties: equals: type: array items: type: string description: >- 源告警与当前事件取值必须相同的 key：`title`、`severity` 或 `labels.<名称>`。列表为空、包含其他 key，或事件缺少该标签时，规则不会抑制任何事件。 source_filters: type: array items: $ref: '#/components/schemas/FilterCondition' description: >- 源告警须满足的 AND 条件。可用的 key：`severity`、`title` 和 `labels.<名称>`；其他 key 返回 `InvalidParameter`。 AlertImage: type: object description: 告警或事件的图片附件。 required: - src properties: href: type: string description: 点击图片时的跳转链接（可选）。 src: type: string description: 图片源地址或内部引用（以 `img_` 或 `http` 开头）。 alt: type: string description: 图片无法显示时展示的替代文字；未设置时为空。 DutyError: type: object description: 响应结构中的错误 payload，仅在非 2xx 响应时出现。 properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- 按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。 example: The specified parameter template_id is not valid. required: - code - message ErrorCode: type: string description: >- 错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。 | 错误码 | HTTP | 含义 | |---|---|---| | `OK` | 200 | 保留值，失败的请求不会返回。 | | `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 | | `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 | | `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 | | `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 | | `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 | | `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 | | `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 | | `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 | | `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 | | `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 | | `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 | | `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 | | `EntityTooLarge` | 413 | 请求体超出大小限制。 | | `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 | | `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 | | `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 | | `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 | | `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 | | `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 | enum: - OK - InvalidParameter - BadRequest - InvalidContentType - ResourceNotFound - NoLicense - ReferenceExist - Unauthorized - BalanceNotEnough - AccessDenied - RouteNotFound - MethodNotAllowed - UndonedOrderExist - EntityTooLarge - RequestLocked - RequestVerifyRequired - DangerousOperation - RequestTooFrequently - InternalError - ServiceUnavailable x-enumDescriptions: OK: 保留值，失败的请求不会返回。 InvalidParameter: 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 BadRequest: 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 InvalidContentType: 请求体没有以 `application/json` 发送。 ResourceNotFound: 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 NoLicense: 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 ReferenceExist: 对象仍被其他对象引用，无法删除。 Unauthorized: APP Key 缺失、无效或已删除。 BalanceNotEnough: 仅用于控制台计费流程，Open API 接口不会返回。 AccessDenied: APP Key 的权限范围或创建者角色不允许该操作或该对象。 RouteNotFound: 没有与该 HTTP 方法和路径匹配的接口。 MethodNotAllowed: 路径存在，但不支持该 HTTP 方法。 UndonedOrderExist: 仅用于控制台计费流程，Open API 接口不会返回。 EntityTooLarge: 请求体超出大小限制。 RequestLocked: 仅用于控制台登录保护，Open API 接口不会返回。 RequestVerifyRequired: 仅用于控制台验证码流程，Open API 接口不会返回。 DangerousOperation: 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 RequestTooFrequently: 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 InternalError: 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 ServiceUnavailable: 后端依赖过载或不可用，请退避后重试。 example: InvalidParameter responses: BadRequest: description: 请求非法 — 通常是参数缺失或格式不正确。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameter: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InvalidParameter message: The specified parameter is not valid. Unauthorized: description: app_key 缺失或无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingAppKey: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: Unauthorized message: You are unauthorized. Forbidden: description: app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noEditPermission: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: AccessDenied message: Access Denied. TooManyRequests: description: 触发频率限制。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: RequestTooFrequently message: Request too frequently. headers: Flashcat-Request-Rate-Limit-Delay: description: 距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。 schema: type: integer minimum: 0 ServerError: description: 服务端未预期错误。反馈问题时请携带 request_id。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal: value: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 error: code: InternalError message: >- We encountered an internal error, and it has been reported. Please try again later. securitySchemes: AppKeyAuth: type: apiKey in: query name: app_key description: >- 在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.