文档中心

Web应用防火墙

Bot 管理

ListBotAnalyseProtectRule - 查询 bot 频率限制或统计防护规则

调用 ListBotAnalyseProtectRule 接口查询指定域名下的 bot 频率限制或统计防护规则详情。

注意事项

服务接口调用总上限：1000 QPS

单账号调用上限：50 QPS

请求说明

请求方式：POST

请求地址：https://waf.volcengineapi.com/?Action=ListBotAnalyseProtectRule&Version=2023-12-25

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

Action String 必选示例值：ListBotAnalyseProtectRule

接口名称。当前 API 的名称为 ListBotAnalyseProtectRule。

Version String 必选示例值：2023-12-25

接口版本。当前 API 的版本为 2023-12-25。

Body

Page Integer 可选示例值：1

查询页码，默认为 1。

ProjectName String 可选示例值：default

所属项目资源名称，获取方式可参考ListProjectResources - 获取项目资源列表。

PageSize Integer 可选示例值：10

单页条数，默认为 10。范围为 1 ~ 100。

Host String 必选示例值：example.volc001.com

查询的域名。

BotSpace String 可选示例值：BotFrequency

Bot 防护规则类型：

BotFrequency：频率限制规则。对应统计内容方式为访问频率。

BotRepeat：统计防护规则。对应统计内容方式为重复次数或重复占比。

RuleTag String 可选示例值：R000000000629

规则唯一标识，用于精确匹配，其实际计数位等于规则Id。例如R000000000629对应的规则Id值为629。

Path String 可选示例值：/path

指定规则适用的请求路径，可填写具体页面路径，也可匹配整站或某个目录下的全部路径（使用通配符*）；通配符 *只能出现在路径末尾。

Name String 可选示例值：rule1

规则名称，用于模糊匹配。

以中文、字母、数字开头

允许字母、数字、中文、点“.”、下划线“_”和中划线“-”

长度为1~128个字符

Region String 必选示例值：cn-beijing

云 WAF 实例所在区域。

华北 2（北京）：cn-beijing

华东 2（上海）：cn-shanghai

华南 1（广州）：cn-guangzhou

中国香港：cn-hongkong

亚太东南（柔佛）：ap-southeast-1

Asia Pacific (Johor)：ap-southeast-1

Asia Pacific (Jakarta)：ap-southeast-3

China (Hong Kong)：cn-hongkong

Edge：byteplus-global

ActionTypeKey Integer[] 可选示例值：-

防护动作的筛选列表，默认值为空数组。支持的取值如下所示。

0：观察；

1：限速；（仅频率限制场景，即StatisticalType=1时支持）

2：拦截；

6：JS挑战；

7：人机验证；

10：工作量证明；

11：动态令牌；

12：丢弃。

返回参数

CurrentPage Integer 示例值：1

当前页码。

Data Object[] 示例值：--

Bot 规则详情。

EnableCount Integer 示例值：1

当前路径下启用的规则数。

Path String 示例值：/login

请求路径。

RuleGroup Object[] 示例值：-

当前路径下按高级条件聚合后的规则列表。

Group Object 示例值：-

高级条件信息，为空表示当前路径下没有高级条件。

AccurateGroupPriority Integer 示例值：10000000

高级条件分组实际对应的优先级，创建规则时无需携带该字段，仅在列表展示高级条件分组时返回该值。

Id Integer 示例值：167913

高级条件分组对应的 ID，创建规则时无需携带该字段，仅在列表展示高级条件分组时用于聚合展示。

Logic Integer 示例值：1

1：与（AND）；

2：或（OR）。

AccurateRules Object[] 示例值：--

高级条件中的子规则列表。

HttpObj String 示例值：request.header.clientip

匹配规则对应的具体对象。支持的匹配对象如下所示：

request.schema：请求协议；

request.uri：请求 URI；

request.method：请求方法；

request.path：请求路径；

request.queryargs：请求参数；

request.header：请求头；

request.header.ua：请求 User-Agent；

request.header.refer：请求 referer；

request.header.cookie：请求 Cookie 头；

request.header.content-length：请求体长度；

request.header.content-type：请求体格式；

request.header.x-forwarded-for：X-Forwarded-For；

request.header.clientip：客户端 IP；

request.queryargs.{Key}：自定义请求参数（需替换 {Key} 为具体参数名）；

request.header.{Key}：自定义请求头（需替换 {Key} 为具体头名称）；

request.cookie.{Key}：自定义 Cookie（需替换 {Key} 为具体 Cookie 名称）；

response.header：响应头；

response.body：响应体；

response.code：响应状态码；

response.header.content-type：响应头 content-type；

response.header.{Key}：自定义响应头（需替换 {Key} 为具体头名称）；

response.body.{Key}：响应体字段（需替换 {Key} 为具体字段名）；

request.ja3-hash：JA3 Hash；（仅 byteplus-global 地域适用）

说明

不能直接传递 request.queryargs.*、request.header.*、request.cookie.*、response.header.*、response.body.*这类泛化形式，必须携带具体的 Key。

ObjType Integer 示例值：12

匹配对象类型的枚举值，用于指定高级条件中子规则的匹配对象类型。支持的取值如下所示：

0：request.schema；

1：request.uri；

2：request.method；

3：request.path；

4：request.queryargs；

5：request.header；

6：request.header.ua；

7：request.header.refer；

8：request.header.cookie；

9：request.header.content-length；

10：request.header.content-type；

11：request.header.x-forwarded-for；

12：request.header.clientip；

13：request.queryargs.{Key}；

14：request.header.{Key}；

15：request.cookie.{Key}；

17：response.header；

18：response.body；

19：response.code；

20：response.header.content-type；

21：response.header.{Key}；

22：response.body.{Key}；

23：request.ja3-hash。（仅 byteplus-global 地域适用）

Opretar Integer 示例值：2

匹配操作符的枚举值，用于指定高级条件中子规则的匹配方式。支持的取值如下所示：

0：大于；

1：大于等于；

2：等于；

3：小于；

4：小于等于；

5：不等于；

6：包含子串；

7：不包含子串；

8：前缀匹配；

9：前缀不匹配；

10：后缀匹配；

11：后缀不匹配；

12：包含全部匹配集；

13：不包含全部匹配集；

14：属于匹配集；

15：不属于匹配集；

16：正则匹配；

17：识别为 IP；

18：识别为 IPv4；

19：识别为 IPv6；

20：识别为私网 IP；

21：识别为公网 IP；

22：保留值；

23：属于 IP 组；

24：不属于 IP 组；

25：属于 IP 地理位置；

26：不属于 IP 地理位置；

27：包含 IP 情报；

28：属于 ASN；

29：不属于 ASN。

Property Integer 示例值：0

匹配属性类型的枚举值，默认使用 0（除 IP 识别类特殊场景外）。支持的取值如下所示：

0：Value，适用于大部分匹配对象场景，如请求协议、URI、方法、请求头、客户端 IP、JA3 Hash 等；

5：IP，仅用于以下 IP 识别类操作

17（识别为 IP）

18（识别为 IPv4）

19（识别为 IPv6）

20（识别为私网 IP）

21（识别为公网 IP）

ValueString String 示例值：1.1.1.1

匹配规则对应的具体值。

当匹配对象为request.header.{Key}、request.queryargs.{Key}或request.cookie.{Key}等泛化对象时，该字段表示对应Key的匹配值。

特殊说明：当操作符（Opretar）为17、18、19、20、21且匹配对象（HttpObj）为request.header.clientip时，无需填写该字段；其余操作符场景均需按实际匹配值填写。

Rules Object[] 示例值：-

当前高级条件分组下的规则列表。

AccurateGroup Object 示例值：-

规则的高级条件配置，包含逻辑关系、子规则列表、优先级等信息

AccurateGroupPriority Integer 示例值：10000000

高级条件分组实际对应的优先级，创建规则时无需携带该字段，仅在列表展示高级条件分组时返回该值。

Id Integer 示例值：167913

高级条件分组对应的 ID，创建规则时无需携带该字段，仅在列表展示高级条件分组时用于聚合展示。

Logic Integer 示例值：1

1：与（AND）；

2：或（OR）。

AccurateRules Object[] 示例值：--

高级条件中的子规则列表。

HttpObj String 示例值：request.header.clientip

匹配规则对应的具体对象。支持的匹配对象如下所示：

request.schema：请求协议；

request.uri：请求 URI；

request.method：请求方法；

request.path：请求路径；

request.queryargs：请求参数；

request.header：请求头；

request.header.ua：请求 User-Agent；

request.header.refer：请求 referer；

request.header.cookie：请求 Cookie 头；

request.header.content-length：请求体长度；

request.header.content-type：请求体格式；

request.header.x-forwarded-for：X-Forwarded-For；

request.header.clientip：客户端 IP；

request.queryargs.{Key}：自定义请求参数（需替换 {Key} 为具体参数名）；

request.header.{Key}：自定义请求头（需替换 {Key} 为具体头名称）；

request.cookie.{Key}：自定义 Cookie（需替换 {Key} 为具体 Cookie 名称）；

response.header：响应头；

response.body：响应体；

response.code：响应状态码；

response.header.content-type：响应头 content-type；

response.header.{Key}：自定义响应头（需替换 {Key} 为具体头名称）；

response.body.{Key}：响应体字段（需替换 {Key} 为具体字段名）；

request.ja3-hash：JA3 Hash；（仅 byteplus-global 地域适用）

说明

不能直接传递 request.queryargs.*、request.header.*、request.cookie.*、response.header.*、response.body.*这类泛化形式，必须携带具体的 Key。

ObjType Integer 示例值：12

匹配对象类型的枚举值，用于指定高级条件中子规则的匹配对象类型。支持的取值如下所示：

0：request.schema；

1：request.uri；

2：request.method；

3：request.path；

4：request.queryargs；

5：request.header；

6：request.header.ua；

7：request.header.refer；

8：request.header.cookie；

9：request.header.content-length；

10：request.header.content-type；

11：request.header.x-forwarded-for；

12：request.header.clientip；

13：request.queryargs.{Key}；

14：request.header.{Key}；

15：request.cookie.{Key}；

17：response.header；

18：response.body；

19：response.code；

20：response.header.content-type；

21：response.header.{Key}；

22：response.body.{Key}；

23：request.ja3-hash。（仅 byteplus-global 地域适用）

Opretar Integer 示例值：2

匹配操作符的枚举值，用于指定高级条件中子规则的匹配方式。支持的取值如下所示：

0：大于；

1：大于等于；

2：等于；

3：小于；

4：小于等于；

5：不等于；

6：包含子串；

7：不包含子串；

8：前缀匹配；

9：前缀不匹配；

10：后缀匹配；

11：后缀不匹配；

12：包含全部匹配集；

13：不包含全部匹配集；

14：属于匹配集；

15：不属于匹配集；

16：正则匹配；

17：识别为 IP；

18：识别为 IPv4；

19：识别为 IPv6；

20：识别为私网 IP；

21：识别为公网 IP；

22：保留值；

23：属于 IP 组；

24：不属于 IP 组；

25：属于 IP 地理位置；

26：不属于 IP 地理位置；

27：包含 IP 情报；

28：属于 ASN；

29：不属于 ASN。

Property Integer 示例值：0

匹配属性类型的枚举值，默认使用 0（除 IP 识别类特殊场景外）。支持的取值如下所示：

0：Value，适用于大部分匹配对象场景，如请求协议、URI、方法、请求头、客户端 IP、JA3 Hash 等；

5：IP，仅用于以下 IP 识别类操作

17（识别为 IP）

18（识别为 IPv4）

19（识别为 IPv6）

20（识别为私网 IP）

21（识别为公网 IP）

ValueString String 示例值：1.1.1.1

匹配规则对应的具体值。

当匹配对象为request.header.{Key}、request.queryargs.{Key}或request.cookie.{Key}等泛化对象时，该字段表示对应Key的匹配值。

特殊说明：当操作符（Opretar）为17、18、19、20、21且匹配对象（HttpObj）为request.header.clientip时，无需填写该字段；其余操作符场景均需按实际匹配值填写。

AccurateGroupPriority Integer 示例值：10000000

高级条件的优先级，列表展示时可根据该值确定拖拽目标位置。

ActionType Integer 示例值：2

执行的动作。支持的取值如下所示：

0：观察；

1：限速；（仅频率限制场景，即StatisticalType=1时支持）

2：拦截；

6：JS挑战；

7：人机验证；

10：工作量证明；

11：丢弃。

EffectTime Integer 示例值：66

动作生效时长，单位为秒。有效范围为 30～86400 秒。

除 ActionType 为 1（限速）外，创建和更新规则时需填写该字段。

Enable Integer 示例值：1

启用状态。支持的取值如下所示：

0：关闭；

1：开启。

ExemptionTime Integer 示例值：30

人机挑战、JS挑战或工作量证明的豁免时间，单位为秒。有效范围为 30～3600 秒。

仅当ActionType为以下值时需要填写：

6：JS挑战

7：人机验证

10：工作量证明

Field String 示例值：HEADER:X-Forwarded-For,CLIENTIP,COOKIE:token

统计规则的统计对象，支持单个或多个字段，多个字段使用英文逗号分隔（最多 10 个）。多个统计对象使用英文逗号拼接，不加空格。

字段格式分为两类：无需 Key 的枚举值和需要 Key 的枚举值。

无需 Key 的枚举值包括：

CLIENTIP：客户端 IP （仅StatisticalType=1时支持）

JA3HASH：JA3 哈希值（仅 byteplus-global 地域适用）。

需要 Key 的枚举值包括：

HEADER:{Header-Name}：指定请求头（例如 HEADER:X-Forwarded-For）；

ARGS:{ArgName}：指定请求参数（例如 ARGS:device_id）；

COOKIE:{CookieName}：指定 Cookie（例如 COOKIE:token）。

Host String 示例值：wafexample.com

需要保护的网站域名。

Id Integer 示例值：18673

规则 ID。

Name String 示例值：bot-frequency-login

规则的名称。

以中文、字母、数字开头。

允许字母、数字、中文、点“.”、下划线“_”和中划线“-”。

长度为1~128个字符

PassRatio Double 示例值：0

JS 挑战或人机验证通过率，仅 ActionType 为以下类型时返回：

6：JS挑战

7：人机验证

10：工作量证明

Path String 示例值：/login

指定规则适用的请求路径，可填写具体页面路径，也可匹配整站或某个目录下的全部路径；通配符 *只能出现在路径末尾。

PathThreshold Integer 示例值：20

当前路径的总体阈值，仅当统计方式为频率限制（StatisticalType=1）时生效，取值范围为 1 到 1000。

RulePriority Integer 示例值：0

规则的优先级，取值范围为 0 到 9。其中 0 为最高优先级，9为最低优先级。

RuleTag String 示例值：R000000018673

规则展示 ID。频率限制规则展示 ID 形如 R000000018673，重复统计规则展示 ID 形如 S000000018674。

SingleProportion Double 示例值：0.6

单个统计对象的占比阈值。仅当StatisticalType为3（重复占比）时启用，此时需传入该字段。取值范围为 [0, 1)。

SingleThreshold Integer 示例值：6

单个统计对象的次数阈值，仅当统计方式为频率限制（StatisticalType=1）时生效，取值范围 1～ 1000 次。

StatisticalDuration Integer 示例值：60

统计时间窗口，单位为秒。不同统计场景下的取值范围不同：

频率限制场景（StatisticalType=1）：取值范围为 5~1800 秒；

重复统计场景（StatisticalType=2 或StatisticalType=3）：取值范围为 1~60 秒。

StatisticalType Integer 示例值：1

统计方式。支持的取值如下所示：

1：访问频率；

2：重复次数；

3：重复占比。

UpdateTime String 示例值：2023-10-09T20:02:42Z

最近更新时间，仅列表展示时返回。

TotalCount Integer 示例值：1

当前路径下规则总数。

PageSize Integer 示例值：10

每页包含的条数上限。

TotalCount Integer 示例值：15

总条数。

Count Integer 示例值：5

当前页面条数。

错误码

您可访问公共错误码，获取更多错误码信息。

输入示例 1

输入示例 2

输入示例

POST https://waf.volcengineapi.com/?Action=ListBotAnalyseProtectRule&Version=2023-12-25&ProjectName=default
X-Date: 20230711T035055Z
Authorization: HMAC-SHA256 Credential=<AccessKeyId>/20230711/cn-beijing/waf/request, SignedHeaders=content-type;x-content-sha256;x-date, Signature=<Signature>

{
  "Host": "wafexample.com",
  "Page": 1,
  "PageSize": 10,
  "Region": "cn-beijing",
  "Path": "",
  "BotSpace": "BotFrequency"
}

输出示例

{
    "ResponseMetadata": {
        "RequestId": "20260525180009FC4D1A2BC4649F15E263",
        "Action": "ListBotAnalyseProtectRule",
        "Version": "2023-12-25",
        "Service": "waf",
        "Region": "cn-beijing"
    },
    "Result": {
        "CurrentPage": 1,
        "PageSize": 10,
        "TotalCount": 1,
        "Count": 1,
        "Data": [
            {
                "Path": "/login",
                "TotalCount": 1,
                "EnableCount": 1,
                "RuleGroup": [
                    {
                        "Group": {
                            "Id": 167913,
                            "AccurateGroupPriority": 10000000,
                            "Logic": 1,
                            "AccurateRules": [
                                {
                                    "HttpObj": "request.cookie.session_id",
                                    "ObjType": 15,
                                    "Property": 0,
                                    "Opretar": 2,
                                    "ValueString": "session-123456"
                                }
                            ]
                        },
                        "Rules": [
                            {
                                "Id": 18673,
                                "Name": "bot-frequency-login",
                                "Host": "wafexample.com",
                                "Path": "/login",
                                "Enable": 1,
                                "AccurateGroupPriority": 10000000,
                                "AccurateGroup": {
                                    "Id": 167913,
                                    "AccurateGroupPriority": 10000000,
                                    "Logic": 1,
                                    "AccurateRules": [
                                        {
                                            "HttpObj": "request.cookie.session_id",
                                            "ObjType": 15,
                                            "Property": 0,
                                            "Opretar": 2,
                                            "ValueString": "session-123456"
                                        }
                                    ]
                                },
                                "Field": "HEADER:X-Forwarded-For,CLIENTIP,COOKIE:token",
                                "StatisticalType": 1,
                                "StatisticalDuration": 66,
                                "SingleThreshold": 6,
                                "SingleProportion": 0,
                                "PathThreshold": 6,
                                "RulePriority": 0,
                                "ActionType": 2,
                                "EffectTime": 66,
                                "ExemptionTime": 30,
                                "UpdateTime": "2026-05-25T09:56:51Z",
                                "PassRatio": 0,
                                "RuleTag": "R000000018673"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

最近更新时间：2026.06.04 15:31:49

这个页面对您有帮助吗？

有用

无用