tencent cloud

APIs

文档APIsTencent Cloud FirewallAccess Control APIsAddAclRule

AddAclRule

Download
聚焦模式
字号
最后更新时间： 2026-08-03 20:57:00

1. API Description

Domain name for API request: cfw.intl.tencentcloudapi.com.

Add one or more Internet Boundary Access Control Rules.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: AddAclRule.
Version Yes String Common Params. The value used for this API: 2019-09-04.
Region No String Common Params. This parameter is not required.
Rules.N Yes Array of CreateRuleItem The list of Internet boundary rules to be added cannot be empty. Each rule must meet the requirements for direction, source and target, action, scope, protocol port, and template restrictions. The entire request must also comply with rule quota and effective rule count limitations. Account-related values must come from read-only queries: for address templates, call DescribeAddressTemplateList, filter the request with TemplateType=1 or 5, and confirm that the returned Data[].Type is 1 or 5. Write Data[].Uuid (with the mb_ prefix) to the corresponding Content, and do not use Data[].TemplateId (with the ip-/dm- prefix). For protocol port templates, filter the request with TemplateType=6, and write Data[].TemplateId (with the pp- prefix) to ParamTemplateId. For asset instances, call DescribeCfwAssets, parse the returned results, and use assets[].instance_id. For asset groups, call DescribeResourceGroupNew, pass QueryType=resource, GroupId="0", ShowType=all, parse the returned results, and use GroupId. For resource tags, pass QueryType=tag, skip the "all assets" root node, and construct JSON using the first-level node GroupName as the Key and the selected second-level sub-node GroupName as the Value, without writing GroupId. For regions, call DescribeAclRegInfo: for Scope=serial, pass FwType=["SERIAL"]; for Scope=side, pass FwType=["BYPASS"]; for Scope=all, pass both items simultaneously, and use Data[].RegionCode. Do not use display names or manually concatenate values. The range for overwrite import is determined solely by the Direction of the first rule.
CfwAiAgentOperationSource No String

AI operation source

Enumeration value:

  • console: console source value
  • wechat: WeChat
From No String Add method. Omit or an empty string means ordinary addition; insert_rule means adding new at a specified position; batch_import means non-overwrite batch import; batch_import_cover means overwrite import, which deletes the existing operation rule corresponding to the first rule's Direction and then adds Rules. Deleted rules will not be restored if addition fails, with extremely high risk. The coverage area is only determined by the first rule. The caller must ensure the Directions of the Rules match. Only the above values are supported.

3. Output Parameters

Parameter Name Type Description
RuleUuid Array of Integer ID list of the added rules, in the same sequence as Rules.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Add an outbound Internet boundary monitoring rule

Add an outbound serial TCP observation rule using the RFC 5737 document address; explicitly specify the enable status, effective scope, rule source, and priority at the end.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
            "SourceContent": "192.0.2.0/24",
            "SourceType": "net",
            "TargetContent": "198.51.100.10",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "true",
"Description": "Outbound TCP observation example"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100001
        ],
        "RequestId": "00000000-0000-4000-8000-000000000001"
    }
}

Example2 Add an inbound region source rule

Add an inbound serial TCP rule, with the source using region code; region code should be obtained through a read-only query, gd44 in the example is only used for display format.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
            "SourceContent": "gd44",
            "SourceType": "location",
            "TargetContent": "198.51.100.0/24",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "accept",
            "Port": "443",
            "Direction": 1,
            "OrderIndex": -1,
            "Enable": "true",
"Description": "Allow region source to access HTTPS"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100002
        ],
        "RequestId": "00000000-0000-4000-8000-000000000002"
    }
}

Example3 Insert a bypass Internet boundary rule

Use insert_rule to insert a disabled outbound bypass rule at a user-specified location. Before invocation, use DescribeCfwRules with RuleType=border, Direction=0, and ExpandNames=false, and write the rules[].sequence corresponding to the target location to OrderIndex.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "From": "insert_rule",
    "Rules": [
        {
            "SourceContent": "192.0.2.0/24",
            "SourceType": "net",
            "TargetContent": "198.51.100.10",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": 3118,
            "Enable": "false",
"Description": "Insert bypass monitoring rule"
            "Scope": "side",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100003
        ],
        "RequestId": "00000000-0000-4000-8000-000000000003"
    }
}

Example4 Batch insert Internet boundary rules at consecutive locations

Two rules use the same Direction and set the OrderIndex to consecutive positions 3 and 4 in request order.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "From": "insert_rule",
    "Rules": [
        {
            "SourceContent": "192.0.2.31",
            "SourceType": "net",
            "TargetContent": "198.51.100.31",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": 3,
            "Enable": "false",
"Description": "Batch insertion of consecutive positions example one"
            "Scope": "serial",
            "RuleSource": 0
        },
        {
            "SourceContent": "192.0.2.32",
            "SourceType": "net",
            "TargetContent": "198.51.100.32",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "8443",
            "Direction": 0,
            "OrderIndex": 4,
            "Enable": "false",
"Description": "Example II of batch insertion at consecutive positions"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100008,
            100009
        ],
        "RequestId": "00000000-0000-4000-8000-000000000008"
    }
}

Example5 Import two global Internet boundary rules in batches

Use a non-overwriting batch_import to add two disabled outbound global rules; this method will not delete existing rules.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "From": "batch_import",
    "Rules": [
        {
            "SourceContent": "192.0.2.1",
            "SourceType": "net",
            "TargetContent": "198.51.100.31",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Batch global rule 1"
            "Scope": "all",
            "RuleSource": 0
        },
        {
            "SourceContent": "192.0.2.2",
            "SourceType": "net",
            "TargetContent": "198.51.100.32",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "8443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Batch global rule 2"
            "Scope": "all",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100004,
            100005
        ],
        "RequestId": "00000000-0000-4000-8000-000000000004"
    }
}

Example6 Using address templates to add new Internet boundary rules

Add one Internet boundary rule using an address template.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
            "SourceContent": "mb_xxxxx_xxxxx",
            "SourceType": "template",
            "TargetContent": "198.51.100.60",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Address template observation rule"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100006
        ],
        "RequestId": "00000000-0000-4000-8000-000000000005"
    }
}

Example7 Adding new Internet boundary rules using resource tags

Call DescribeResourceGroupNew with QueryType=tag, and construct an access source using the first-level node GroupName as the Key and the selected second-level sub-node GroupName as the Value.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
"SourceContent": "{\"Key\":\"automatic test\",\"Value\":\"autotest\"}"
            "SourceType": "tag",
            "TargetContent": "198.51.100.60",
            "TargetType": "net",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Resource tag observation rule"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100007
        ],
        "RequestId": "00000000-0000-4000-8000-000000000006"
    }
}

Example8 Allow Tencent Cloud source to access specified asset

When a user requires permission for Tencent Cloud source to access a specified asset, first call DescribeCfwAssets, select the target asset that has a public IP address and use assets[].instance_id; the cloud service provider uses the usage agreement value tencent, do not fill in the display name "Tencent Cloud".

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
            "SourceContent": "tencent",
            "SourceType": "vendor",
            "TargetContent": "ins-xxxxxxxx",
            "TargetType": "instance",
            "Protocol": "ANY",
            "RuleAction": "log",
            "Port": "-1/-1",
            "Direction": 1,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Monitor Tencent Cloud source access to specified asset"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100010
        ],
        "RequestId": "00000000-0000-4000-8000-000000000010"
    }
}

Example9 Add DNS loose and strict match rules

When users require controlling outbound access based on domain name resolution results, they can add two rules in the same direction in batches: dnsparse hits when Host/SNI matches or the destination IP belongs to the current DNS resolution result, while domainiptwoverify requires both conditions to be satisfied simultaneously. Both rules use the precise domain name from queries or user confirmation, without using a separate *.

Input Example

POST / HTTP/1.1
Host: cfw.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddAclRule
<Common request parameters>

{
    "Rules": [
        {
            "SourceContent": "192.0.2.0/24",
            "SourceType": "net",
            "TargetContent": "example.com",
            "TargetType": "dnsparse",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Monitor DNS loose match traffic"
            "Scope": "serial",
            "RuleSource": 0
        },
        {
            "SourceContent": "192.0.2.0/24",
            "SourceType": "net",
            "TargetContent": "example.org",
            "TargetType": "domainiptwoverify",
            "Protocol": "TCP",
            "RuleAction": "log",
            "Port": "443",
            "Direction": 0,
            "OrderIndex": -1,
            "Enable": "false",
"Description": "Monitor DNS strict match traffic"
            "Scope": "serial",
            "RuleSource": 0
        }
    ]
}

Output Example

{
    "Response": {
        "RuleUuid": [
            100011,
            100012
        ],
        "RequestId": "00000000-0000-4000-8000-000000000011"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
AuthFailure CAM signature/authentication error.
DryRunOperation DryRun operation, which means the DryRun parameter is passed in yet the request will still be successful.
FailedOperation Operation failed.
InternalError Internal error.
InvalidParameter Invalid parameter.
InvalidParameterValue Invalid parameter value.
LimitExceeded The quota limit has been reached.
MissingParameter Missing parameter.
OperationDenied Operation denied.
RequestLimitExceeded The number of requests exceeds the frequency limit.
ResourceInUse The resource is occupied.
ResourceInsufficient Insufficient resource.
ResourceNotFound The resource does not exist.
ResourceUnavailable The resource is unavailable.
ResourcesSoldOut The resources have been sold out.
UnauthorizedOperation Unauthorized operation.
UnknownParameter Unknown parameter error.
UnsupportedOperation Unsupported operation.
上一篇: ModifyEnterpriseSecurityDispatchStatus下一篇: DescribeVpcAcRule

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈