WAF3.0 API

POST 编辑自定义限速规则

POST /prod-api/waf/wafv3/limit/rules/modifyLimitRule

新增或更新自定义限速规则。匹配条件、相同特征、运算符请先通过 查询条件参数 获取；编辑前可先 查询自定义限速规则 回显。

与自定义控制规则的主要区别

项目	自定义控制规则	自定义限速规则（本接口）
规则 ID 字段	customRuleId	limitRuleId
条件结构	conditions 为二维数组（组内与、组间或）	conditions 为一维数组（全部为与）
相同特征	无	characteristics 必填（1–10 项），定义计数维度
命中动作	DENY / LOG / SKIP_RULES 等	仅 DENY / LOG，且须配置 limitAccess、limitTime、parameters.behavior（及 duration）

控制台配置与 API 字段对照

限速规则编辑页在「匹配条件」之外，还有计数维度与速率阈值等字段，对应关系如下：

控制台区域	API 字段	说明
规则名称	ruleMessage	规则描述，最长 30 字符
如果传入请求匹配…（匹配类型 / 运算符 / 值）	rules.conditions[]	一维数组，多条为 And（与）；决定「哪些流量参与本条限速」
具有相同特征…（下拉，如 IP）	rules.characteristics[]	定义按什么维度累计请求次数；提交时仅需 target、name（见下节）
当速率超过… → 请求	rules.action.limitAccess	统计时间窗内允许的最大请求次数（整数，如 12）
当速率超过… → 期间	rules.action.limitTime	统计时间窗长度，单位秒（如 10 表示 10 秒）；控制台可选 10 秒、1 分钟等，提交为秒数
然后采取措施… → 操作	rules.action.action	DENY（拦截）或 LOG（仅记录不拦截）
使用以下行为（单选）	rules.action.parameters.behavior	excess 或 all
在所选持续时间内阻止 → 下拉	rules.action.parameters.duration	仅当 behavior=all 时必填；触发阈值后持续阻断的秒数（1–86400）

behavior 与控制台文案对应：

behavior	控制台选项（含义）
excess	限制超过最大配置速率的请求：仅对超出 limitAccess 的请求执行 action，其余放行
all	在所选持续时间内阻止：达到阈值后，在 duration 秒内对全部匹配请求执行 action

说明： limitTime 是「计数窗口」（多久内统计是否超过 N 次）；duration 是 behavior=all 时「惩罚窗口」（触发后阻断多久）。二者单位均为秒，数值可以相同（如均为 10），含义不同。

characteristics 提交说明： 保存接口只需 target、name（如 { "target": "IP_SRC", "name": "IP_SRC" }）。查询回显或前端调试时可能附带 parameter（来自 describeParameter 的元数据），提交时无需传递 parameter。

填写说明

场景	limitRuleId	说明
新增	请求体中不传	服务端创建新规则并返回规则 ID
编辑	必填	取自 列出自定义限速控制规则 或 查询自定义限速规则

Body 请求参数

新增示例（对应控制台：规则名「11」、匹配 IP 在数据集合 black、相同特征 IP、12 次/10 秒、拦截、behavior=all 且持续 10 秒）：

{
  "ruleMessage": "11",
  "status": "enable",
  "wafId": 22,
  "rules": {
    "characteristics": [
      { "target": "IP_SRC", "name": "IP_SRC" }
    ],
    "conditions": [
      {
        "target": "IP_SRC",
        "operator": "IP_IN_LIST",
        "name": "IP_SRC",
        "values": ["52"]
      }
    ],
    "action": {
      "action": "DENY",
      "limitAccess": 12,
      "limitTime": 10,
      "parameters": {
        "behavior": "all",
        "duration": 10
      }
    }
  }
}

上例含义：仅当源 IP 在数据集合 52（控制台展示名如 black）内时参与统计；按 IP 聚合计数；10 秒内超过 12 次请求则触发；触发后在 10 秒内拦截全部匹配请求（behavior=all + duration=10）。

behavior=excess 示例（仅限制超出阈值的请求，无需 duration）：

{
  "ruleMessage": "单IP超限仅拦超出部分",
  "status": "enable",
  "wafId": 22,
  "rules": {
    "characteristics": [
      { "target": "IP_SRC", "name": "IP_SRC" }
    ],
    "conditions": [
      {
        "target": "IP_SRC",
        "operator": "IP_IN_LIST",
        "name": "IP_SRC",
        "values": ["52"]
      }
    ],
    "action": {
      "action": "DENY",
      "limitAccess": 12,
      "limitTime": 10,
      "parameters": {
        "behavior": "excess"
      }
    }
  }
}

编辑示例（必传 limitRuleId）：

{
  "limitRuleId": 15,
  "ruleMessage": "11",
  "status": "enable",
  "wafId": 22,
  "rules": {
    "characteristics": [
      { "target": "IP_SRC", "name": "IP_SRC" }
    ],
    "conditions": [
      {
        "conditionId": 120000501,
        "target": "IP_SRC",
        "operator": "IP_IN_LIST",
        "name": "IP_SRC",
        "values": ["52"]
      }
    ],
    "action": {
      "action": "DENY",
      "limitAccess": 12,
      "limitTime": 10,
      "parameters": {
        "behavior": "all",
        "duration": 10
      }
    }
  }
}

请求参数

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

返回示例

200 Response

{
  "msg": "成功",
  "code": 200,
  "data": 15
}

data 为保存后的 limitRuleId（新增时为新 ID，编辑时为原 ID）。

返回结果

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

Body 请求参数字段说明

字段	类型	必选	说明
limitRuleId	integer(int64)	编辑必填	规则 ID；新增不传
wafId	integer(int64)	是	策略组 ID
ruleMessage	string	是	规则描述/名称，最长 30 字符
status	string	是	enable / disable
sort	integer	否	排序号；新增时一般由服务端排到末尾
rules	object	是	含 characteristics、conditions、action

rules.characteristics[]（相同特征，必填）

对应控制台 「具有相同特征…」。决定计数器按什么键聚合（如每个 IP 单独计数）。

字段	类型	必选	说明
target	string	是	特征编码，与 describeParameter 中 targets[].target 一致，如 IP_SRC（控制台显示为「IP」）
name	string	是	子字段名；多数与 target 相同；仅允许 [a-zA-Z0-9_.-]+

至少 1 项、至多 10 项；可点 「+ And」 增加多项（如 IP_SRC + REQUEST_URI 表示按「IP + URI」组合计数）。

提交时不要传 parameter（该字段为前端回显用，来自 describeParameter）。

rules.conditions[]（匹配条件，必填）

一维数组，全部条件同时满足时规则才生效。至少 1 条。

字段	类型	说明
target	string	匹配对象，与 describeParameter 中 targets[].target 一致
operator	string	运算符，如 EQ、IP_IN_LIST
values	string[]	比较取值；数据集合填 dataListId
name	string	子字段名；为空时服务端按 target 填充
conditionId	integer	编辑时由服务端生成/回显；新增条件由服务端分配

rules.action（限速动作，必填）

对应控制台 「当速率超过…」、「然后采取措施…」、「使用以下行为」 三块配置。

字段	类型	必选	控制台位置	说明
limitAccess	integer	是	请求（必需）	时间窗内允许的请求次数上限，如 12
limitTime	integer	是	期间（必需）	统计时间窗，秒；如 10（10 秒）。须 > 0
action	string	是	操作	DENY 拦截 / LOG 仅记录不拦截
parameters	object	是	使用以下行为	含 behavior、可选 duration

parameters

字段	类型	必选	控制台位置	说明
behavior	string	是	使用以下行为（单选）	excess 或 all
duration	integer	条件	behavior=all 时的持续时间下拉	behavior=all 时必填；秒，范围 1–86400。behavior=excess 时不传或传 null

behavior 说明

值	含义
excess	时间窗内计数超过 limitAccess 后，对超出部分执行 action（其余请求正常放行）
all	计数达到阈值后，在 duration 秒内对所有匹配请求执行 action

limitTime 常用取值（秒）

值	含义（示例）
10	10 秒
60	1 分钟
300	5 分钟
3600	1 小时

控制台下拉选项以实现为准，提交时为整型秒数即可。