跳转至

WAF3.0 API

POST 列出托管规则明细

POST /prod-api/waf/wafv3/custody/rules/describeCustodyRuleList

在指定 策略组（wafId） 下，按 规则组（groupId） 分页查询托管检测单条规则列表。用于控制台点击某个规则组后展示组内规则，或按条件筛选规则。

Body 请求参数

{
  "pageNum": 1,
  "pageSize": 20,
  "wafId": 22,
  "groupId": 901,
  "params": {},
  "filters": []
}

按规则 ID 筛选示例（filters 仅传需要的一项或多项）：

{
  "pageNum": 1,
  "pageSize": 20,
  "wafId": 22,
  "groupId": 901,
  "params": {},
  "filters": [
    {
      "label": "ruleId",
      "value": ["901450"]
    }
  ]
}

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 鉴权 Bearer Token
body body object 是 请求体 见下表

Body 字段说明

字段 类型 必选 说明
wafId integer(int64) 是 策略组 ID
groupId integer(int64) 是 规则组 ID，与 列出托管规则组 的 groupId 一致
pageNum integer 是 页码，从 1 开始
pageSize integer 是 每页条数
params object 否 扩展参数，一般传 {}
filters array 否 筛选条件，见下文「filters」
searchHeader object 否 可选，按 status 筛选（如 switchMode: "ON"）

userId 由服务端根据登录态自动填充，无需在请求体中传递。

filters（可选筛选）

filters 为对象数组，用于在指定 groupId 范围内进一步过滤规则。

字段 类型 说明
label string 筛选字段，仅支持：ruleId、ruleMessage、groupName
value string[] 筛选取值列表

匹配规则：

  • value 只有 1 个元素时：对该字段做 模糊匹配（LIKE %值%）。
  • value 有 多个元素时：对该字段做 精确 IN 匹配（等于列表中任一值）。

label 可用取值：

label 含义 示例
ruleId 规则 ID "value": ["901450"]
ruleMessage 规则说明（模糊） "value": ["配置是否进行有效"]
groupName 规则组英文名 "value": ["REQUEST-INITIALIZATION"]

多条件同时传入时，条件之间为 与（AND） 关系。

多字段筛选示例：

"filters": [
  {
    "label": "ruleMessage",
    "value": ["采样率"]
  },
  {
    "label": "groupName",
    "value": ["REQUEST-INITIALIZATION"]
  }
]

返回示例

200 Response

{
  "total": 3,
  "rows": [
    {
      "ruleId": 901001,
      "ruleMessage": "基础规则：检查配置是否进行有效配置",
      "groupName": "REQUEST-INITIALIZATION",
      "defaultStatus": "ON",
      "status": "DEFAULT"
    },
    {
      "ruleId": 901450,
      "ruleMessage": "规则引擎已根据采样率暂停执行",
      "groupName": "REQUEST-INITIALIZATION",
      "defaultStatus": "ON",
      "status": "DEFAULT"
    },
    {
      "ruleId": 901500,
      "ruleMessage": "检测偏执级别低于设定值，属于非法操作。请求已强制阻断。",
      "groupName": "REQUEST-INITIALIZATION",
      "defaultStatus": "ON",
      "status": "DEFAULT"
    }
  ],
  "code": 200,
  "msg": "成功"
}

返回结果

状态码 状态码含义 说明
200 OK 成功
401 Unauthorized 未授权
403 Forbidden 无权限

返回数据结构

状态码 200

名称 类型 必选 说明
total integer 是 符合条件的规则总数
rows [object] 是 当前页规则列表
code integer 是 200 表示成功
msg string 是 提示信息

rows[] 每条规则

字段 类型 说明
ruleId integer 托管规则 ID；
ruleMessage string 规则说明/描述，供列表展示
groupName string 所属规则组英文标识，如 REQUEST-INITIALIZATION
defaultStatus string 平台对该规则的默认推荐状态
status string 当前策略组下该规则的实际状态

defaultStatus / status 取值

值 含义
ON 启用
OFF 关闭
DEFAULT 跟随默认/未单独配置（status 为 DEFAULT 时表示未在策略组上覆盖，按 defaultStatus 或系统逻辑生效）

如何理解两个状态字段：

字段 说明
defaultStatus 规则库内置的推荐开关，一般不变
status 用户在当前 wafId 上的配置；DEFAULT 表示「未显式设为 ON/OFF」

修改单条规则请调用 changeCustodyRuleStatus，将 status 设为 ON 或 OFF（或恢复为 DEFAULT）。