Creating an ACL Rule

Function

This API is used to create an ACL rule.

URI

POST /v1/{project_id}/acl-rule

Table 1 Path Parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID, which can be obtained by calling an API or from the console. For details, see Obtaining a Project ID.

Table 2 Query Parameters

Parameter	Mandatory	Type	Description
enterprise_project_id	No	String	Enterprise project ID, which is the ID of a project planned based on organizations. You can obtain the enterprise project ID by referring to Obtaining an Enterprise Project ID. If the enterprise project function is not enabled, the value is 0.
fw_instance_id	No	String	Firewall ID, which can be obtained by referring to Obtaining a Firewall ID.

Request Parameters

Table 3 Request header parameters

Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. You can obtain the token by referring to Obtaining a User Token.
Content-Type	Yes	String	Content type. It can only be set to application/json.

Table 4 Request body parameters

Parameter	Mandatory	Type	Description
object_id	Yes	String	Protected object ID, which is used to distinguish between Internet border protection and VPC border protection after a cloud firewall is created. You can obtain the ID by calling the API for querying firewall instances. In the return value, find the ID in data.records.protect_objects.object_id (The period [.] is used to separate different levels of objects). If the value of type is 0, the protected object ID belongs to the Internet border. If the value of type is 1, the protected object ID belongs to the VPC border. You can obtain the value of type from data.records.protect_objects.type (The period [.] is used to separate different levels of objects).
type	Yes	Integer	Rule type: 0 (Internet border rule), 1 (inter-VPC rule), or 2 (NAT rule). When type is set to 0, the source and destination addresses of the rule must be EIPs or domain names of the public network. For an inter-VPC rule, the source and destination addresses must be private IP addresses. For a NAT rule, the source address must be a private IP address, and the destination address must be an EIP or domain name of the public network.
rules	Yes	Array of rules objects	Rule list in a rule addition request.

Table 5 rules

Parameter	Mandatory	Type	Description
name	Yes	String	Rule name.
sequence	Yes	OrderRuleAclDto object	Request body for changing the rule sequence.
address_type	Yes	Integer	Address type: 0 (IPv4), 1 (IPv6).
action_type	Yes	Integer	Rule action: 0 (permit), 1 (deny).
status	Yes	Integer	Rule status: 0 (disabled), 1 (enabled).
applications	No	Array of strings	Rule application list. Rule application type: HTTP, HTTPS, TLS1, DNS, SSH, MYSQL, SMTP, RDP, RDPS, VNC, POP3, IMAP4, SMTPS, POP3S, FTPS, ANY, or BGP.
applicationsJsonString	No	String	JSON string converted from the applications field in the application list.
long_connect_time	No	Long	Persistent connection duration.
long_connect_time_hour	No	Long	Persistent connection duration (hour).
long_connect_time_minute	No	Long	Persistent connection duration (minute).
long_connect_time_second	No	Long	Persistent connection duration (second).
long_connect_enable	Yes	Integer	Whether to support persistent connections: 0 (no), 1 (yes).
description	No	String	Description.
direction	No	Integer	Direction: 0 (inbound) or 1 (outbound). This parameter is mandatory when type is set to 0 (Internet rule) or 2 (NAT rule).
source	Yes	RuleAddressDtoForRequest object	Source address Data Transport Object.
destination	Yes	RuleAddressDtoForRequest object	Destination address Data Transport Object.
service	Yes	RuleServiceDto object	Service object.
tag	No	TagsVO object	Tag object attached to a rule.

Table 6 OrderRuleAclDto

Parameter	Mandatory	Type	Description
dest_rule_id	No	String	ID of the target rule. The added rule is placed after this rule. This parameter cannot be left blank when the added rule is not pinned on top, and can be left blank when the added rule is pinned on top. The rule ID can be obtained by calling the API for querying protection rules. Find the value in data.records.rule_id (The period [.] is used to separate different levels of objects).
top	No	Integer	Whether to pin on top: 0 (no), 1 (yes).
bottom	No	Integer	Whether to pin to bottom: 0 (no), 1 (yes).

Table 7 RuleAddressDtoForRequest

Parameter	Mandatory	Type	Description
type	Yes	Integer	Address type: 0 (manual input), 1 (associated IP address group), 2 (domain name), 3 (geographical location), 4 (domain name group) 5 (multiple objects), 6 (domain name group - network), 7 (domain name group - application).
address_type	No	Integer	Address type: 0 (IPv4), 1 (IPv6). If type is 0, the input cannot be left blank.
address	No	String	IP address information. It cannot be left blank if type is set to 0.
address_set_id	No	String	ID of an associated IP address group. This parameter cannot be left blank when type is set to 1. You can obtain the value by calling the API for querying the address group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects).
address_set_name	No	String	Name of an associated IP address group. This parameter cannot be left blank when type is set to 1. You can obtain the value by calling the API for querying the address group list. Find the value in data.records.name (The period [.] is used to separate different levels of objects).
domain_address_name	No	String	Name of a domain name address. This parameter is valid when type is set to 2 (domain name) or 7 (application domain name group).
region_list_json	No	String	JSON value of the rule region list.
region_list	No	Array of IpRegionDto objects	Rule region list.
domain_set_id	No	String	Domain group ID. The value cannot be left blank when type is set to 4 (domain name group) or 7 (domain name group - application). Its value can be obtained by calling the API for querying the domain name group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects).
domain_set_name	No	String	Domain group name. The value cannot be left blank when type is set to 4 (domain name group) or 7 (domain name group - application). Its value can be obtained by calling the API for querying the domain name group list. Find the value in data.records.name (The period [.] is used to separate different levels of objects).
ip_address	No	Array of strings	IP address list. This parameter cannot be left blank when type is set to 5 (multiple objects).
address_set_type	No	Integer	Address group type. It cannot be left blank when type is set to 1 (associated IP address group). It value can be 0 (user-defined address group), 1 (WAF back-to-source IP address group), 2 (DDoS back-to-source IP address group), or 3 (NAT64 address group).
predefined_group	No	Array of strings	Pre-defined address group ID list. This parameter cannot be left blank when type is set to 5 (multiple objects). Its value can be obtained by calling the API for querying the address group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects). In the search criteria, query_address_set_type must be set to 1 (predefined address group).
address_group	No	Array of strings	Address group ID list. This parameter cannot be left blank when type is set to 5 (multiple objects). Its value can be obtained by calling the API for querying the address group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects). In the search criteria, query_address_set_type must be set to 0 (user-defined address group).

Table 8 IpRegionDto

Parameter	Mandatory	Type	Description
region_id	No	String	Region ID. You can obtain the ID by referring to Obtaining Information About Account, IAM User, Group, Project, Region, and Agency.
region_type	No	Integer	Region type: 0 (country), 1 (province), and 2 (continent). It can be obtained from the region information table.

Table 9 RuleServiceDto

Parameter	Mandatory	Type	Description
type	Yes	Integer	Service input type: 0 (manual), 1 (automatic).
protocol	No	Integer	Protocol type: 6 (TCP), 17 (UDP), 1 (ICMP), 58 (ICMPv6), or -1 (any). It cannot be left blank when type is set to 0 (manual).
protocols	No	Array of integers	Protocol list. Protocol type: 6 (TCP), 17 (UDP), 1 (ICMP), 58 (ICMPv6), or -1 (any). It cannot be left blank when type is set to 0 (manual).
source_port	No	String	Source port.
dest_port	No	String	Destination port.
service_set_id	No	String	Service group ID. This parameter cannot be left blank when type is set to 1 (associated IP address group). Its value can be obtained by calling the API for querying the service group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects).
service_set_name	No	String	Service group name. This parameter cannot be left blank when type is set to 1 (associated IP address group). Its value can be obtained by calling the API for querying the service group list. Find the value in data.records.name (The period [.] is used to separate different levels of objects).
custom_service	No	Array of ServiceItem objects	Custom service.
predefined_group	No	Array of strings	Predefined service group ID list. The service group ID can be obtained by calling the API for querying the service group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects). In the search criteria, query_service_set_type must be set to 1 (predefined service group).
service_group	No	Array of strings	Service group ID list. The service group ID can be obtained by calling the API for querying the service group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects). In the search criteria, query_service_set_type must be set to 0 (user-defined service group).
service_group_names	No	Array of ServiceGroupVO objects	Service group name list.
service_set_type	No	Integer	Service group type: 0 (user-defined service group), 1 (common web service), 2 (common remote login and ping), or 3 (common database).

Table 10 ServiceItem

Parameter	Mandatory	Type	Description
protocol	No	Integer	Protocol type: 6 (TCP), 17 (UDP), 1 (ICMP), 58 (ICMPv6), or -1 (any). It cannot be left blank when RuleServiceDto.type is set to 0 (manual).
source_port	No	String	Source port.
dest_port	No	String	Destination port.
description	No	String	Service member description.
name	No	String	Service member name.

Table 11 ServiceGroupVO

Parameter	Mandatory	Type	Description
name	No	String	Service group name.
protocols	No	Array of integers	Protocol list. Protocol type: 6 (TCP), 17 (UDP), 1 (ICMP), 58 (ICMPv6), or -1 (any).
service_set_type	No	Integer	Service group type: 0 (user-defined service group), 1 (predefined service group).
set_id	No	String	Service group ID, which can be obtained by calling the API for querying the service group list. Find the value in data.records.set_id (The period [.] is used to separate different levels of objects).

Table 12 TagsVO

Parameter	Mandatory	Type	Description
tag_id	No	String	Rule ID.
tag_key	No	String	Rule tag key.
tag_value	No	String	Rule tag value.

Response Parameters

Status code: 200

Table 13 Response body parameters

Parameter	Type	Description
data	RuleIdList object	Data of the return value for creating a rule.

Table 14 RuleIdList

Parameter	Type	Description
rules	Array of RuleId objects	Rule ID list.

Table 15 RuleId

Parameter	Type	Description
id	String	Rule ID.
name	String	Rule name.

Status code: 400

Table 16 Response body parameters

Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error description.

Example Requests

The following example shows how to add an IPv4 inbound rule. The rule name is Test rule, the source is the IP address 1.1.1.1, the destination is the IP address 2.2.2.2, the service type is service, the protocol type is TCP, the source port is 0, and the destination port is 0. Persistent connections are not supported. The action is to allow. The status is enabled.

https://{Endpoint}/v1/9d80d070b6d44942af73c9c3d38e0429/acl-rule

{
  "object_id" : "ae42418e-f077-41a0-9d3b-5b2f5ad9102b",
  "rules" : [ {
    "name" : "Test rule.",
    "status" : 1,
    "action_type" : 0,
    "description" : "",
    "source" : {
      "type" : 0,
      "address" : "1.1.1.1"
    },
    "destination" : {
      "type" : 0,
      "address" : "2.2.2.2"
    },
    "service" : {
      "type" : 0,
      "protocol" : 6,
      "source_port" : "0",
      "dest_port" : "0"
    },
    "address_type" : 0,
    "tag" : {
      "tag_key" : "",
      "tag_value" : ""
    },
    "long_connect_enable" : 0,
    "direction" : 0,
    "sequence" : {
      "top" : 1,
      "dest_rule_id" : null
    }
  } ],
  "type" : 0
}

Example Responses

Status code: 200

Response to the request for creating an ACL rule.

{
  "data" : {
    "rules" : [ {
      "id" : "0475c516-0e41-4caf-990b-0c504eebd73f",
      "name" : "testName"
    } ]
  }
}

Status code: 400

Bad Request

{
  "error_code" : "CFW.00900016",
  "error_msg" : "Import is in progress. Please wait until it is complete."
}

Status Codes

Status Code	Description
200	Response to the request for creating an ACL rule.
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

Error Codes

See Error Codes.

last updated: 2025-01-21 13:19 UTC - commit: abe94c6df6d30c3b44340c2119ffd81f9990504a