> ## 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`） | ## 使用说明 * 不会保存任何内容，也不创建告警或事件。 * `integration_id` 必须是本账户的集成，且调用方有权读取它。 * `mapping_type` 为 `api` 的 `mapping` 规则会用已存的请求头调用账户的映射 API，因此还需要编辑该集成的权限，否则请求失败。 * `before` 是事件进入时的样子，`after` 是规则执行后的事件；`steps` 逐条说明规则是否满足条件、为什么被跳过、新增/删除/改写了哪些标签。 * 触发事件会按接入在增强后的方式渲染，因此 `after` 中的 `[TPL]` 标签、标题和描述就是最终形态。 * `if` 的条件键必须来自告警或变更事件的键（`title`、`description`、`labels.` 等），其他键返回 `InvalidParameter`。 ## OpenAPI ````yaml /api-reference/on-call.openapi.zh.json post /enrichment/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: /enrichment/preview: post: tags: - On-call/标签增强 summary: 预览标签增强规则效果 description: 用未保存的标签增强规则按接入的方式处理一个事件，返回规则逐步的结果。 operationId: enrichment-read-preview requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EnrichmentPreviewRequest' example: integration_id: 6113996590131 rules: - kind: extraction if: - key: labels.env oper: IN vals: - prod settings: source_field: labels.host result_label: service_name pattern: ^(?P[a-z0-9-]+)-\d+$ override: false event: title: CPU usage 94% on checkout-7 description: CPU usage above 90% for 5 minutes. event_status: Critical labels: env: prod host: checkout-7 check: cpu responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - type: object properties: data: $ref: '#/components/schemas/EnrichmentPreviewResponse' example: request_id: 01HK8XQE3Z7JM2NTFQ5YJ8P9R4 data: before: title: CPU usage 94% on checkout-7 labels: check: cpu env: prod host: checkout-7 after: title: CPU usage 94% on checkout-7 labels: check: cpu env: prod host: checkout-7 service_name: checkout steps: - index: 0 kind: extraction matched: true skipped_reason: '' detail: checkout added: service_name: checkout removed: null changed: null mapping_row: null '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: EnrichmentPreviewRequest: type: object description: '`POST /enrichment/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/EnrichRule' 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 EnrichmentPreviewResponse: type: object description: 标签增强预览的结果。 required: - before - after - steps properties: before: $ref: '#/components/schemas/EnrichmentPreviewEvent' description: 事件进入时的样子。 after: $ref: '#/components/schemas/EnrichmentPreviewEvent' description: 规则执行后的事件，触发事件已按接入方式渲染 `[TPL]` 标签、标题和描述。 steps: type: array items: $ref: '#/components/schemas/EnrichStep' description: 每条规则一项，按执行顺序排列。 EnrichRule: type: object required: - kind - settings description: 带可选条件的富化规则，包含特定类型配置。 properties: kind: type: string enum: - extraction - composition - mapping - drop description: >- 规则类型。 | 值 | 含义 | |---|---| | `extraction` | 通过正则或 GJson 从告警的 `title`、`description` 或 `labels.*` 键提取值并写入标签。 | | `composition` | 用 Go `text/template` 对事件渲染模板，结果写入标签。 | | `mapping` | 从映射规则或外部映射 API 查找标签。 | | `drop` | 从告警中删除指定标签。 | if: type: - array - 'null' items: $ref: '#/components/schemas/EnrichFilter' description: >- 可选的 AND 过滤条件列表；所有条件都匹配时才执行该规则。无条件时为 `null`。过滤键来自告警/变更事件的键集合（如 `title`、`labels.severity`）。 settings: description: 与规则类型对应的配置，具体结构由 `kind` 字段决定。 discriminator: propertyName: kind mapping: extraction: '#/components/schemas/ErsExtraction' composition: '#/components/schemas/ErsComposition' mapping: '#/components/schemas/ErsMapping' drop: '#/components/schemas/ErsDrop' oneOf: - $ref: '#/components/schemas/ErsExtraction' - $ref: '#/components/schemas/ErsComposition' - $ref: '#/components/schemas/ErsMapping' - $ref: '#/components/schemas/ErsDrop' 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: 事件附带的图片。 EnrichmentPreviewEvent: type: object description: 标签增强预览当时的事件。 required: - title - labels properties: title: type: string description: 执行到当前步骤时的事件标题。 labels: type: object additionalProperties: type: string description: 执行到当前步骤时的标签集合。 EnrichStep: type: object description: 单条标签增强规则对事件做了什么。 required: - index - kind - matched - skipped_reason - detail - added - removed - changed - mapping_row properties: index: type: integer description: 规则在 `rules` 中的位置，从 0 开始。 kind: type: string enum: - extraction - composition - mapping - drop description: >- 执行过的规则类型。 | 取值 | 含义 | |---|---| | `extraction` | 通过正则或 GJson 从事件 `title`、`description` 或 `labels.*` 中提取值并写入标签。 | | `composition` | 用模板渲染事件并把结果写入标签。 | | `mapping` | 从映射规则或外部映射 API 查询标签。 | | `drop` | 从告警中删除指定标签。 | matched: type: boolean description: 规则的 `if` 条件是否全部满足；`false` 表示规则没有改变任何标签。 skipped_reason: type: string description: >- 规则被跳过的原因：`condition_not_met`、`regex_not_matched`、`source_label_missing`、`mapping_row_not_found`、`result_label_exists` 或 `error`。规则正常执行时为空。 detail: type: string description: 规则自身的细节：命中的映射行、渲染出的值，`skipped_reason` 为 `error` 时为错误信息。 added: type: - object - 'null' additionalProperties: type: string description: 规则新写入的标签；未新增时为 `null`。 removed: type: - array - 'null' items: type: string description: 规则删除的标签；未删除时为 `null`。 changed: type: - object - 'null' additionalProperties: type: string description: 规则改写的标签，每个值为 `[旧值, 新值]` 两元数组；未改写时为 `null`。 mapping_row: type: - object - 'null' additionalProperties: type: string description: 规则命中的映射行；不是映射规则或未命中时为 `null`。 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 EnrichFilter: type: object required: - key - oper - vals description: 单个标签过滤条件。 properties: key: type: string description: >- 要匹配的事件键：`title`、`description`、`labels.` 或其他告警 / 变更事件键。`labels.` 中的标签名须合法。 minLength: 1 oper: type: string enum: - IN - NOTIN description: |- 匹配操作符。 - `IN`：键的值匹配 `vals` 中任意一个即命中；事件中不存在该键时不命中。 - `NOTIN`：键的值不匹配 `vals` 中任何一个即命中；事件中不存在该键时总是命中。 vals: type: array items: type: string description: >- 要匹配的值（至少一个）。每个值可以是：精确字符串；`/regex/` 形式的正则表达式；含 `*`、`?` 的通配符；`cidr:`（如 `cidr:203.0.113.0/24`）表示 IP 网段；`num:lt:`、`num:le:`、`num:gt:`、`num:ge:` 表示数值比较。 minItems: 1 ErsExtraction: type: object title: extraction required: - source_field - result_label properties: source_field: type: string description: >- 待提取的源字段。可为 `title`、`description` 或以 `labels.` 为前缀的标签键（如 `labels.env`）。 result_label: type: string description: 提取值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ pattern: type: string description: >- 作用于来源值的正则表达式（RE2），可以用 `/.../` 包裹。所有捕获组以空格拼接后写入 `result_label`。未匹配、没有捕获组或第一个捕获组为空时不写入。`pattern` 与 `g_json` 必须且只能设置一个。 g_json: type: string description: >- 当来源值是 JSON 字符串时使用的 GJSON 路径（开头的 `$.` 会被忽略），如 `host.name`。来源值不是合法 JSON 时跳过该规则；路径不存在时写入空字符串。`pattern` 与 `g_json` 必须且只能设置一个。 override: type: boolean description: 为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。 ErsComposition: type: object title: composition required: - result_label - template properties: result_label: type: string description: 组合值写入的目标标签键名，须匹配 `^[a-zA-Z_][a-zA-Z0-9_]*$`。 pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ template: type: string maxLength: 500 description: >- Go `text/template` 模板串（1–500 字符），基于事件结构体渲染，如 `{{.Title}}`、`{{.Description}}`、`{{.Labels.key}}`。示例：`{{.Labels.region}}-{{.Labels.env}}`。 minLength: 1 override: type: boolean description: 为 `false`（默认）时，若事件已有 `result_label` 标签则跳过该规则；为 `true` 时覆盖已有值。 ErsMapping: type: object title: mapping required: - result_labels properties: result_labels: type: array items: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ description: >- 要用查找结果填充的标签键（至少一个）。`schema` 方式下通常取映射规则的 `result_labels`；`api` 方式下会作为 `result_label_keys` 发送给 API。 minItems: 1 mapping_type: type: string enum: - schema - api default: schema description: >- 查找来源。 - `schema`（默认）：用事件中该映射规则 `source_labels` 的值，在映射规则 `schema_id` 中查找数据行；缺少任一来源标签或未匹配到行时不生效。 - `api`：携带事件调用映射 API `api_id`；只对告警事件生效。 schema_id: type: string description: 映射规则 ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `schema` 时必填。 api_id: type: string description: 映射 API ID（MongoDB ObjectID 十六进制）。`mapping_type` 为 `api` 时必填。 override: type: boolean description: >- 为 `false`（默认）时，若 `result_labels` 中的标签都已存在则跳过该规则，否则只填充缺失的标签；为 `true` 时用查找结果覆盖全部 `result_labels`。 ErsDrop: type: object title: drop required: - drop_labels properties: drop_labels: type: array items: type: string description: 要从事件中删除的标签名（至少一个），不带 `labels.` 前缀。 minItems: 1 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.