文档中心

Web应用防火墙

访问管控

ListAclRule - 查询访问管控规则

ListAclRule 接口用于查询访问管控规则信息详情，您需要明确查询的规则类型是禁止访问名单还是允许访问名单。

注意事项

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

单账号调用上限：50 QPS

请求说明

请求方式：POST

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

请求参数

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

Query

Action String 必选示例值：ListAclRule

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

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

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

Body

AclType String 必选示例值：Block

访问管控规则类型。

Allow：允许访问名单

Block：禁止访问名单

Action String[] 可选示例值：["observe"]

执行动作。

block：拦截

observe：观察

DefenceHost String[] 可选示例值：["example.volcwaf002.com"]

查询的域名列表。

Enable Integer[] 可选示例值：[1]

规则的启用状态。

0：关闭

1：启用

Page Integer 可选示例值：1

查询页码，默认为 1。

PageSize Integer 可选示例值：10

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

RuleName String 可选示例值：访问控制1

规则名称，模糊搜索。

RuleTag String 可选示例值：B000000116869

规则唯一标识符，精确搜索。

TimeOrderBy String 可选示例值：ASC

列表展示时序。

ASC：按更新时间升序，即最近更新的在列表最前。

DESC：按更新时间降序，即最近更新的在列表最后。

ProjectName String 可选示例值：default

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

返回参数

Rules Object[] 示例值：-

ACL 规则的列表，每个元素代表一条具体的 ACL 规则。

AccurateGroup Object 示例值：-

高级条件，未配置时无需此字段。

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 名称）；

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}；

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；

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时，无需填写该字段；其余操作符场景均需按实际匹配值填写。

id Integer 示例值：1

高级条件实际对应的 ID，创建时无需携带，仅列表展示时关注此 ID 进行聚合展示。

logic Integer 示例值：1

逻辑关系：

1：与(AND)

2：或(OR)

Action String 示例值：block

执行动作：

block：拦截

observe：观察

AddSrc Integer 示例值：1

预留字段，无实际含义。

Advanced Integer 示例值：0

是否启用高级条件：

0：关闭

1：开启

ClientIp String 示例值：IPLIST_DEMO

规则生效的客户端 IP 信息。

Description String 示例值：ACL rule example

规则描述信息。

Enable Integer 示例值：0

是否启用该规则：

0：关闭

1：开启

Host String 示例值：www.example.com

规则生效的域名。

HostAddType Integer 示例值：2

域名添加方式

2：域名组

3：手动输入单个或多个域名

HostGroupId Integer[] 示例值：[8561]

当域名添加方式（HostAddType）为 2（域名组添加方式）时返回的域名组 ID 列表。

HostGroups Object[] 示例值：-

当域名添加方式（HostAddType）为 2（域名组添加方式）时返回的域名组详细信息列表。

HostGroupId Integer 示例值：8561

域名组的唯一标识 ID，当 ACL 规则的域名添加方式（HostAddType）为 2（域名组添加方式）时，返回的域名组详细信息中的域名组 ID。

Name String 示例值：FooName

域名组的名称，当 ACL 规则的域名添加方式（HostAddType）为 2（域名组添加方式）时，返回的域名组详细信息中的域名组名称。

HostList String[] 示例值：["www.example.com"]

当域名添加方式（HostAddType）为 3（多域名添加模式）时返回的域名列表，包含该 ACL 规则生效的多个域名。

ID Integer 示例值：259227

ACL规则的唯一标识，用于唯一识别每条规则。

IpAddType Integer 示例值：3

IP 添加方式，支持的取值如下所示。

2：地址组；

3：多 IP；

4：地理位置。

IpGroupId Integer[] 示例值：[17401]

当IP添加方式（IpAddType）为2（地址组添加模式）时返回的地址组ID列表。

IpGroups Object[] 示例值：-

当IP添加方式（IpAddType）为 2（地址组添加模式）时返回的地址组详细信息列表，每个元素包含地址组ID和名称。

IpGroupId Integer 示例值：17401

地址组的唯一标识 ID，当 ACL 规则的 IP 添加方式（IpAddType）为 2（地址组添加模式）时，返回的地址组详细信息中的地址组 ID。

Name String 示例值：AllowIPGroup001

地址组的名称，用于标识该地址组。当ACL规则的IP添加方式（IpAddType）为2（地址组添加模式）时，返回该字段。

IpList String[] 示例值：["1.1.1.1"]

当IP添加方式（IpAddType）为3（多IP添加模式）时返回的IP或CIDR列表，用于指定该ACL规则生效的客户端IP范围。

IpLocationCountry String[] 示例值：["US"]

当IpAddType为4（地理位置添加模式）时返回的字段，包含地理位置模式下使用的国家编码列表，编码示例取自GetAreaBlockInfo返回的OverSeaAreaInfoList中的AreaCode。

IpLocationSubregion String[] 示例值：["Beijing"]

当IpAddType为4（地理位置添加模式）时返回的字段，包含该规则生效的子区域编码列表，编码示例取自GetAreaBlockInfo接口返回的CNAreaInfoList中的AreaCode。

仅适用于火山引擎 WAF 服务，使用 BytePlus WAF 服务时不生效。

Name String 示例值：AclAllowRuleDemo

ACL 规则的名称，用于标识每条规则的含义或用途。

PermitFeature String[] 示例值：["allowlist"]

白名单放行的防护规则列表，空时默认表示全量放行。放行后，相关请求将不再经由对应规则检测。

支持的取值如下所示：

allowlist：全部允许访问；

blocklist：禁止访问名单；

geo_black：地理位置访问控制；

api_route：未登记 API 检测；

api_schema：API 防护参数校验；

api_sensitive：API 敏感信息防护；

bot_dytoken：BOT 动态令牌；

bot_frequency：BOT 频率限制；

bot_repeat：BOT 统计防护；

bot_sequence：BOT 行为地图；

user_ua_bot：BOT 自定义规则；

bot_ua_system：BOT 托管规则；

httpflood：CC 自定义规则；

vuln_signature：漏洞防护；

scan_freqvuln：高频扫描；

bot_session_protection：BOT 会话防护

PrefixSwitch Integer 示例值：0

预留字段，无实际含义。

RuleTag String 示例值：B000000227102

规则展示 ID。

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

规则更新时间。

Url String 示例值：/demo/path

生效路径。

Count Integer 示例值：5

当前页实际返回的 ACL 规则数量。

CurrentPage Integer 示例值：1

当前返回结果的页码，用于标识分页查询中当前数据所在的页。

PageSize Integer 示例值：10

每页返回的 ACL 规则数量。

TotalCount Integer 示例值：10

符合查询条件的 ACL 规则总数量，用于分页场景下计算总页数或判断是否有更多数据。

错误码

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

输入示例 1

输入示例

POST https://waf.volcengineapi.com/?Action=ListAclRule&Version=2023-12-25
X-Date: 20230711T035055Z
Authorization: HMAC-SHA256 Credential=AKLTNGU0OGEyMT***/20230711/cn-beijing/waf/request, SignedHeaders=content-type;x-content-sha256;x-date, Signature=da4fac562d00f41ad8***

{
  "AclType": "Block",
  "DefenceHost": [
    "www.example.com"
  ],
  "Enable": [
    1
  ],
  "Page": 1,
  "PageSize": 10,
  "ProjectName": "default",
  "RuleName": "AclBlockRuleDemo",
  "RuleTag": "B000000072784",
  "TimeOrderBy": "DESC"
}

输出示例

{
    "ResponseMetadata": {
        "RequestId": "202605292318116A96B83ED66F99E1****",
        "Action": "ListAclRule",
        "Version": "2023-12-25",
        "Service": "waf",
        "Region": "byteplus-global"
    },
    "Result": {
        "Rules": [
            {
                "Name": "AclBlockRuleDemo",
                "Description": "",
                "Url": "/black_list.html",
                "Host": "HOSTLIST_3615175949",
                "ClientIp": "1.2.3.4",
                "IpAddType": 1,
                "IpList": null,
                "IpGroupId": null,
                "IpGroups": null,
                "IpLocationCountry": null,
                "IpLocationSubregion": null,
                "HostAddType": 3,
                "HostList": [
                    "www.example.com"
                ],
                "HostGroupId": null,
                "HostGroups": null,
                "Advanced": 0,
                "Enable": 1,
                "Action": "block",
                "AccurateGroup": {
                    "Id": 0,
                    "Logic": 0,
                    "AccurateRules": null
                },
                "AddSrc": 1,
                "PrefixSwitch": 0,
                "ID": 72784,
                "RuleTag": "B000000072784",
                "UpdateTime": "2026-05-29T15:15:10Z",
                "PermitFeature": [
                    "allowlist"
                ]
            }
        ],
        "PageSize": 10,
        "Count": 1,
        "CurrentPage": 1,
        "TotalCount": 1
    }
}

最近更新时间：2026.06.03 17:05:18

这个页面对您有帮助吗？

有用

无用