跳转到主要内容
POST
批量更新规则字段

限制说明

使用说明

  • 每个列出的字段取同名请求字段的值;列出但未传值的字段会被设为零值(例如 fields 包含 labels 却既不传 labels 也不传 labels_patch,会清空全部标签)。未列出的字段保持原值。
  • fields 中出现未知字段名、传入 labels_patch / annotations_patch 但 fields 未包含对应字段,或同时传入 labels 与 labels_patch(annotations 与 annotations_patch 同理)时,整个调用返回 InvalidParameter。
  • 规则逐条更新,结果为每个 ID 返回一项:成功时 message 为空,否则为该规则的错误信息(校验失败、对其所在文件夹无权限,或 ID 不存在,此时 name 为 id: <id>)。
  • 将 enabled 设为 false 会清理这些规则的活跃告警。除非本次调用只是停用规则(fields 恰好为 ["enabled"] 且 enabled: false),否则账户规则数超出告警规则 License 上限时返回 AccessDenied,且非管理员调用者须对每条规则选中的所有数据源具备只读权限。
  • 每次调用都会记录到账户审计日志,请不要把敏感信息放在请求字段中。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json
ids
integer<uint64>[]
必填

要更新的规则 ID 列表,包含 1 到 100 个 ID。

Required array length: 1 - 100 elements
fields
enum<string>[]
必填

要更新的字段名列表。每个列出的字段取同名请求字段的值,未传值时设为零值;未列出的字段即使传值也会被忽略。出现未知字段名时整个调用返回 InvalidParameter。

可用选项:
labels,
ds_type,
ds_list,
ds_ids,
enabled,
debug_log_enabled,
cron_pattern,
timezone,
delay_seconds,
enabled_times,
annotations,
description,
channel_ids,
repeat_interval,
repeat_total
labels
object

自定义标签键值对,整体替换现有标签。仅当 fields 包含 labels 时生效;不能与 labels_patch 同时传入。

ds_type
string

数据源类型标识。启用的规则必须使用支持告警的类型:prometheus、elasticsearch、loki、clickhouse、mysql、oracle、postgres、sls、tencent_cls、victorialogs。仅当 fields 包含 ds_type 时生效。

ds_list
string[]

数据源名称匹配模式列表,支持通配符。仅当 fields 包含 ds_list 时生效。

ds_ids
integer<uint64>[]

数据源 ID 列表,与 ds_list 合并后共同决定规则监控的数据源,使用 ID 可避免数据源改名后失效。仅当 fields 包含 ds_ids 时生效。

enabled
boolean

是否启用规则。置为 false 时服务端会清理该规则的活跃告警。仅当 fields 包含 enabled 时生效。

debug_log_enabled
boolean

是否开启调试日志,开启后 edge 评估该规则时输出详细日志,用于排查问题。仅当 fields 包含 debug_log_enabled 时生效。

cron_pattern
string

调度表达式:6 段(含秒)cron 表达式或 @every 30s 间隔描述,不允许 CRON_TZ=/TZ= 前缀。仅当 fields 包含 cron_pattern 时生效。

timezone
string
默认值:Asia/Shanghai

规则执行时区,取 IANA 时区名(如 Asia/Shanghai、UTC);为空时按 Asia/Shanghai 处理。仅当 fields 包含 timezone 时生效。

delay_seconds
integer

评估时查询窗口向前偏移的秒数,用于补偿数据摄入延迟。仅当 fields 包含 delay_seconds 时生效。

enabled_times
object[]

规则生效的时间窗口数组,元素结构见 EnabledTime。仅当 fields 包含 enabled_times 时生效。

annotations
object

随告警事件下发的注解键值对,整体替换现有注解,键不允许以 $ 开头(该前缀保留给查询字段)。仅当 fields 包含 annotations 时生效;不能与 annotations_patch 同时传入。

description
string

规则描述,按规则现有的 description_type 渲染(本接口无法修改该格式)。仅当 fields 包含 description 时生效。

channel_ids
integer<uint64>[]

告警发送到的协作空间 ID 列表,可为空。仅当 fields 包含 channel_ids 时生效。

repeat_interval
integer<int64>

告警通知重复间隔(秒);小于 1 时按 3600 处理,最大 2147483647。仅当 fields 包含 repeat_interval 时生效。

repeat_total
integer<int64>

最大重复通知次数;小于 1 时按 3 处理,最大 2147483647。仅当 fields 包含 repeat_total 时生效。

labels_patch
object

标签的增量更新,未提及的标签保持不变。要求 fields 包含 labels,且不能与 labels 同时传入,否则返回 InvalidParameter。

annotations_patch
object

注解的增量更新,未提及的注解保持不变。要求 fields 包含 annotations,且不能与 annotations 同时传入,否则返回 InvalidParameter。

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse。

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object[]

批量规则操作中每条规则的处理结果列表。