文档中心

Web应用防火墙

CC 防护

CreateCCRule - 创建 CC 防护规则

调用 CreateCCRule 接口创建 CC 防护规则，根据网络访问 IP、Session 等各种 HTTP 请求对象进行请求限制。当满足设定的统计条件后，对后续请求执行防护动作，以防止服务器资源被过度占用，确保正常访问业务不受影响。

注意事项

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

单账号调用上限：50 QPS

请求说明

请求方式：POST

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

请求参数

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

Query

Action String 必选示例值：CreateCCRule

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

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

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

Body

AccurateGroup Object 可选示例值：--

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

AccurateGroupPriority Integer 可选示例值：1

高级条件组的优先级，用于在列表展示时判定拖拽优先级时目标的位置。

AccurateRules Object[] 必选示例值：-

高级条件组中的子规则列表，每个子规则定义了具体的匹配条件（如请求头、客户端 IP 等），用于精确筛选符合条件的请求。

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.*这类泛化形式，必须携带具体的 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，创建规则时无需携带，仅在列表展示时用于聚合相关的 CC 防护规则。

Logic Integer 必选示例值：1

高级条件组中子规则之间的逻辑关系。支持的取值如下所示：

1：与（AND）；

2：或（OR）。

CCType Integer 可选示例值：0

满足统计条件后对后续请求执行的动作，关于执行动作的详细说明请参考执行动作说明。

0：观察

1：限速

2：拦截

6：JS 挑战

7：人机验证

CountTime Integer 可选示例值：60

策略的统计周期，单位：秒。取值范围 5～1,800。

CronEnable Integer 可选示例值：0

是否设置周期循环生效，开启后，可在每周固定时间内执行该策略，支持配置多个生效时段。默认为不开启，即永久生效。

0：不开启

1：开启，需要配置周期循环详情。

EffectTime Integer 必选示例值：100

限制时长，即动作的生效时长，单位：秒。取值范围 1～86,400。

说明

当策略执行动作为拦截、人机验证或 JS 挑战时需要设置。例如设置拦截动作的限制时长为 60 秒，则触发策略后，后续请求将被限制在 60 秒内无法访问目标路径。

Enable Integer 必选示例值：1

是否启用规则。

0：不启用

1：启用

CronConfs Object[] 可选示例值：--

周期循环配置详情。CronEnable=1 时需要填写。

Crontab String 必选示例值：* 18-20 * * 1,2,3,4,5

crontab 表达式，需满足 confcenter 的 crontab 校验规则，推荐格式为 * <startHour>-<endHour> * * <weekList>（例如 * 18-20 * * 1,2,3,4,5），且同一规则内的周配置需保持一致，小时区间不能重叠。

PathThreshold Integer 必选示例值：500

定时生效时段内，该路径下的总体请求阈值，取值范围为 1 到 300000次。

SingleThreshold Integer 必选示例值：50

定时生效时段内，单个统计对象的请求次数阈值，取值范围为 1 到 300000次。

RulePriority Integer 必选示例值：0

规则执行优先级，数字越大优先级越低。

0：P0

1：P1

2：P2

3：P3

4：P4

5：P5

6：P6

7：P7

8：P8

9：P9

Url String 必选示例值：/test/*

需要防护的网站请求路径，可以是具体的某个页面路径，也可以是整个网站下的所有路径。

匹配具体路径：某个具体的页面路径，例如需要拦截对 test.com/test.html 的访问，则直接填写域名后的路径信息 /test.html 即可。

匹配目录下全部路径：使用 * 可以匹配全部路径，且 * 需在路径末尾。

匹配整个网站下的所有路径，则填写 /* 即可。

匹配某个目录下的全部路径，则在对应目录路径下使用 * 即可。例如 /test/*，表示匹配 /test/ 目录下的全部路径。

注意

/test/*/abc.html 和 /test/ 都表示匹配 /test/目录下的全部路径。

SingleThreshold Integer 可选示例值：10

每个统计对象访问的次数阈值，单位：次，取值范围 1~300,000。

RuleTag String 可选示例值：F000000001193

规则展示 ID。

注意

调用创建、更新接口时无需传入该参数。

Name String 必选示例值：123

规则名称。

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

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

长度为 1~128 个字符。

ExemptionTime Integer 可选示例值：60

策略豁免时间，当策略执行动作为人机验证或 JS 挑战时需要设置。

当请求行为触发以上防护动作并验证通过之后，流量在豁免时间内可以正常访问目标域名。

豁免时间到期后，如果仍处于策略限制时长范围内，则 WAF 会重新发起人机验证、JS 挑战或工作量证明，通过后才能访问。

Field String 必选示例值：CLIENTIP

统计对象，支持单个或多个字段，多个字段使用英文逗号分隔，最多 10 个。基础格式为 DataType:Value，例如 HEADER:Authorization、COOKIE:PHPSESSID、ARGS:device_id、CLIENTIP。支持的统计对象取值如下所示：

CLIENTIP：源 IP；

HEADER:{Header-Name}：指定请求头（Header-Name 需满足 HTTP 头 Key 规范）；

ARGS:{ArgName}：指定请求参数；

COOKIE:{CookieName}：指定 Cookie；

JA3HASH：JA3 Hash。（仅 byteplus-global 地域适用）

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

需要设置防护规则的网站域名。请确保输入的域名已经添加到 WAF 实例。

PathThreshold Integer 可选示例值：100

请求路径访问的次数阈值。取值范围 1~300,000。

ProjectName String 可选示例值：default

项目名称，即为当前资源关联对应项目，仅可关联当前身份下具有权限的项目。项目名称获取方式可参考ListProjectResources - 获取项目资源列表。

AccurateGroupPriority Integer 可选示例值：1

高级条件的优先级，创建或更新规则时无需指定该字段，在列表展示时用于判定拖拽优先级时目标的位置。

CustomResponsePageID String 可选示例值：123456

自定义响应页面的 ID，空字符串表示未配置，默认值为空字符串。使用前需确保用户已开通并有权限使用对应的自定义响应页面。

WSCdnByteThreshold Integer 可选示例值：1024

WebSocket 字节数阈值，取值范围为 1～10000000。当值为 0 时表示未配置该阈值。需注意，若开启 WebSocket 统计防护（WSCdnEnable=1），则该字段需与 WSCdnFrameThreshold至少配置其中之一。

WSCdnEnable Integer 可选示例值：0

WebSocket 统计防护的开关。开启后，至少需要配置 WSCdnFrameThreshold 或 WSCdnByteThreshold 其中之一，且不支持再叠加 Cron 定时配置。支持的取值如下所示：

0：关闭；

1：开启。

WSCdnFrameThreshold Integer 可选示例值：10

WebSocket 帧数阈值，取值范围为 1～10000。当值为 0 时表示未配置该阈值。需注意，若开启 WebSocket 统计防护（WSCdnEnable=1），则该字段需与 WSCdnByteThreshold至少配置其中之一。

WSCdnUnit String 可选示例值：KB

WebSocket 字节数阈值单位：KB / MB / GB。

返回参数

Id Integer 示例值：1

新建或更新后的规则 ID。

错误码

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

输入示例 1

输入示例

POST https://waf.volcengineapi.com/?Action=CreateCCRule&Version=2023-12-25

{
    "AccurateGroup": {
        "Logic": 1,
        "AccurateRules": [
            {
                "HttpObj": "request.schema",
                "ObjType": 0,
                "Opretar": 2,
                "Property": 0,
                "ValueString": "http"
            }
        ]
    },
    "CCType": 0,
    "CountTime": 60,
    "CronEnable": 0,
    "EffectTime": 100,
    "Enable": 1,
    "CronConfs": [
        {
            "Crontab": "* 18-20 * * 1,2,3,4,5",
            "PathThreshold": 1000,
            "SingleThreshold": 100
        }
    ],
    "RulePriority": 0,
    "Url": "/test/*",
    "SingleThreshold": 10,
    "RuleTag": "F000000001193",
    "Name": "123",
    "ExemptionTime": 60,
    "Field": "CLIENTIP",
    "Host": "example.volcwaf001.com",
    "PathThreshold": 100,
    "ProjectName": "default"
}

输出示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateCCRule",
        "Version": "2023-12-25",
        "Service": "waf",
        "Region": "cn-beijing"
    },
    "Result": {
        "Id": 126217
    }
}

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

这个页面对您有帮助吗？

有用

无用