CreateRule - Server Load Balancer

Creates a forwarding rule for a listener.

Operation description

Take note of the following limits:

When you configure the Redirect action, you can use the default value only for the HttpCode parameter. Do not use the default values for the other parameters.
If you specify the Rewrite action together with other actions in a forwarding rule, make sure that the ForwardGroup action is specified.
CreateRule is an asynchronous operation. After a request is sent, the system returns a request ID and runs the task in the background. You can call the ListRules operation to query the status of a forwarding rule.
- If a forwarding rule is in the Provisioning state, the forwarding rule is being created.
- If a forwarding rule is in the Available state, the forwarding rule is created.
You can set RuleConditions and RuleActions to add conditions and actions to a forwarding rule. The limits on conditions and actions are:
- Limits on conditions: 5 for a basic Application Load Balancer (ALB) instance, 10 for a standard ALB instance, and 10 for a WAF-enabled ALB instance.
- Limits on actions: 3 for a basic ALB instance, 5 for a standard ALB instance, and 5 for a WAF-enabled ALB instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Debug

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

Parameter	Type	Required	Description	Example
ListenerId	string	Yes	The listener ID of the ALB instance.	lsr-bp1bpn0kn908w4nbw****
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.	5A2CFF0E-5718-45B5-9D4D-70B3FF3898
DryRun	boolean	No	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs a dry run. The system checks the request for potential issues, including missing parameter values, incorrect request syntax, and service limits. If the request fails the dry run, an error code is returned. If the request passes the dry run, the `DryRunOperation` error code is returned. false (default): performs a dry run and performs the actual request. If the request passes the dry run, a `2xx HTTP` status code is returned and the operation is performed.	false
Priority	integer	Yes	The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates a higher priority. Note The priorities of the forwarding rules created for the same listener must be unique.	10
Direction	string	No	The direction to which the forwarding rule is applied. Valid values: Request (default): The forwarding rule is applied to the requests received by ALB. Response: The forwarding rule is applied to the responses returned by backend servers. Note Basic ALB instances do not support the Response value.	Request
RuleActions	array<object>	Yes	The maximum cache time of dry run requests in the browser. Unit: seconds. Valid values: -1 to 172800.
	object	Yes	The headers that can be exposed. You can specify an asterisk (`*`) or one or more values. Separate multiple values with commas (,). A single value can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-). It can be up to 32 characters in length.
FixedResponseConfig	object	No	The configuration of the custom response.
Content	string	No	The content of the custom response. The content can be up to 1 KB in size and can contain only ASCII characters.	dssacav
ContentType	string	No	The format of the response. Valid values: text/plain, text/css, text/html, application/javascript, and application/json.	text/plain
HttpCode	string	No	The HTTP status code in the response. Valid values: HTTP_2xx, HTTP_4xx, and HTTP_5xx. x must be a digit.	HTTP_200
ForwardGroupConfig	object	No	The server groups to which requests are distributed. Each forwarding rule supports at most five server groups.
ServerGroupTuples	array<object>	No	The server groups to which requests are distributed. Each forwarding rule supports at most five server groups.
	object	No	The server groups to which requests are distributed.
ServerGroupId	string	No	The server group to which requests are distributed.	sgp-k86c1ov501id6p****
Weight	integer	No	The weight of the server group. A larger value specifies a higher weight. A server group with a higher weight receives more requests. Valid values: 0 to 100. If only one destination server group exists and you do not specify a weight, the default value 100 is used. If more than one destination server group exists, you must specify weights.	100
ServerGroupStickySession	object	No	The configuration of session persistence for server groups.
Enabled	boolean	No	Specifies whether to enable session persistence. Valid values: true false (default)	false
Timeout	integer	No	The timeout period of sessions. Unit: seconds. Valid values: 1 to 86400. Default value: 1000.	100
InsertHeaderConfig	object	No	The configuration of the header to be inserted.
Key	string	No	The key of the header. The key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header key specified by InsertHeaderConfig must be unique. Note You cannot specify the following header keys (case-insensitive): `slb-id`, `slb-ip`, `x-forwarded-for`, `x-forwarded-proto`, `x-forwarded-eip`, `x-forwarded-port`, `x-forwarded-client-srcport`, `connection`, `upgrade`, `content-length`, `transfer-encoding`, `keep-alive`, `te`, `host`, `cookie`, `remoteip`, and `authority`.	key
Value	string	No	The value of the header to be inserted. If ValueType is set to SystemDefined, you can specify one of the following header values: ClientSrcPort: the client port. ClientSrcIp: the client IP address. Protocol: the request protocol (HTTP or HTTPS). SLBId: the ID of the ALB instance. SLBPort: the listening port. If ValueType is set to UserDefined, you can specify a custom header value. The header value must be 1 to 128 characters in length, and can contain printable characters whose ASCII values are `greater than or equal to 32 and lower than 127`. You can use asterisks () and question marks (?) as wildcards. The value cannot start or end with a space character. If ValueType* is set to ReferenceHeader, you can reference one of the request headers. The header value must be 1 to 128 characters in length, and can contain lowercase letters, digits, underscores (_), and hyphens (-).	UserDefined
ValueType	string	No	The type of header. Valid values: UserDefined: a custom header ReferenceHeader: a header that references one of the request headers SystemDefined: a header predefined by the system	UserDefined
Order	integer	Yes	The priority of the action. Valid values: 1 to 50000. A smaller value indicates a higher priority. The actions of a forwarding rule are applied in descending order of priority. This parameter is required. The priority of each action within a forwarding rule must be unique.	1
RedirectConfig	object	No	The redirect configuration. Note When you configure the RedirectConfig action, you can use the default value only for the httpCode parameter. Do not use the default values for the other parameters.
Host	string	No	The hostname to which requests are redirected. Valid values: ${host} (default): If you set the value to ${host}, you cannot append other characters. A custom value. Make sure that the custom value meets the following requirements: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & \| ( ) [ ] ?. The hostname must contain at least one period (.) but cannot start or end with a period (.). The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost `domain label` can be an asterisk (). The domain labels cannot start or end with a hyphen (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	${host}
HttpCode	string	No	The redirect type. Valid values: 301, 302, 303, 307, and 308.	301
Path	string	No	The path to which requests are redirected. Valid values: Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. A custom value. You must make sure that the custom value meets the following requirements: The value must be 1 to 128 characters in length, and can contain asterisks () and question marks (?) as wildcards. The value is case-sensitive. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ :`. It cannot contain the following special characters: `" % # ; ! ( ) [ ] ^ , "`. You can use asterisks () and question marks (?) as wildcard characters.	/test
Port	string	No	The port to which requests are redirected. ${port} (default): If you set the value to ${port}, you cannot add other characters to the value. You can also enter a port number. Valid values: 1 to 63335.	10
Protocol	string	No	The redirect protocol. Valid values: ${protocol} (default): If you set the value to ${protocol}, you cannot add other characters to the value. HTTP or HTTPS. Note HTTPS listeners support only HTTPS to HTTPS redirects.	HTTP
Query	string	No	The query string of the URL to which requests are redirected. Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. A custom value. You must make sure that the custom value meets the following requirements: The value must be 1 to 128 characters in length. It can contain printable characters, except space characters, the special characters `# [ ] { } \ \| < > &`, and uppercase letters.	${query}
RewriteConfig	object	No	The rewrite configuration. Note If multiple actions are configured within a forwarding rule, you must set RewriteConfig to the value of ForwardGroup.
Host	string	No	The hostname to which requests are redirected. Valid values: ${host} (default): If you set the value to ${host}, you cannot append other characters. If you want to specify a custom value, make sure that the following requirements are met: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & \| ( ) [ ] ?. The hostname must contain at least one period (.) but cannot start or end with a period (.). The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost `domain label` can be an asterisk (). The domain labels cannot start or end with a hyphen (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	www.example.com
Path	string	No	The path to which requests are redirected. Valid values: Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. A custom value. You must make sure that the custom value meets the following requirements: The value must be 1 to 128 characters in length, and can contain asterisks () and question marks (?) as wildcards. The value is case-sensitive. It must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ :`. It cannot contain the following special characters: `" % # ; ! ( ) [ ] ^ , "`. You can use asterisks () and question marks (?) as wildcard characters.	/tsdf
Query	string	No	The query string of the URL to which requests are redirected. Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. You can specify one or more of the preceding variables in each request. You can also combine them with a custom value. A custom value. You must make sure that the custom value meets the following requirements: The value must be 1 to 128 characters in length. It can contain printable characters, except space characters, the special characters `# [ ] { } \ \| < > &`, and uppercase letters.	${query}
Type	string	Yes	The action type. Valid values: ForwardGroup: forwards a request to multiple vServer groups. Redirect: redirects a request. FixedResponse: returns a custom response. Rewrite: rewrites a request. InsertHeader: inserts a header. RemoveHeaderConfig: deletes a header. TrafficLimitConfig: throttles network traffic. TrafficMirrorConfig: mirrors traffic. CorsConfig: forwards requests based on CORS. The following action types are supported: FinalType: the last action to be performed in a forwarding rule. Each forwarding rule can contain only one FinalType action. You can specify the ForwardGroup, Redirect, or FixedResponse action as the FinalType action. ExtType: the action or the actions to be performed before the FinalType action. A forwarding rule can contain one or more ExtType actions. To specify this parameter, you must also specify FinalType. You can specify multiple InsertHeader actions or one Rewrite action.	ForwardGroup
TrafficLimitConfig	object	No	The action to throttle traffic.
QPS	integer	No	The queries per second (QPS). Valid values: 1 to 100000.	100
PerIpQps	integer	No	The QPS of each IP address. Valid values: 1 to 100000. Note If both the QPS and PerIpQps properties are specified, make sure that the value of the QPS property is smaller than the value of the PerIpQps property.	80
TrafficMirrorConfig	object	No	The action to mirror traffic.
TargetType	string	No	The type of destination to which network traffic is mirrored. Valid values: ForwardGroupMirror: a server group SlsMirror: Log Service	ForwardGroupMirror
MirrorGroupConfig	object	No	The configuration of the server group to which traffic is mirrored.
ServerGroupTuples	array<object>	No	The configuration of the server group to which traffic is mirrored.
	object	No	The server group to which network traffic is mirrored.
ServerGroupId	string	No	The ID of the server group.	sgp-00mkgijak0w4qgz9****
CorsConfig	object	No	The origins allowed.
AllowOrigin	array	No	The allowed origins of CORS requests.
	string	No	The source site that is allowed to access the destination. You can specify an asterisk (``) or one or more values. The values cannot be asterisks (``). A value must start with `http://` or `https://`, followed by a valid domain name or a first-level wildcard domain name, such as `.test.abc.example.com`. You can specify a port in a value. Port range: 1 to 65535*.	http://example.com
AllowMethods	array	No	The allowed HTTP methods for CORS requests.
	string	No	The allowed HTTP methods for CORS requests. Valid values: GET POST PUT DELETE HEAD OPTIONS PATCH	GET
AllowHeaders	array	No	The allowed headers for CORS requests.
	string	No	The allowed headers for CORS requests. You can specify an asterisk (`*`) or one or more values. Separate multiple values with commas (,). A value can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-). It can be up to 32 characters in length.	test_123
ExposeHeaders	array	No	The headers that can be exposed.
	string	No	The headers that can be exposed. You can specify `*` or specify one or more values. Separate multiple values with commas (,). A value can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-). It can be up to 32 characters in length.	test_123
AllowCredentials	string	No	Specifies whether credentials can be carried in CORS requests. Valid values: on: yes off: no	on
MaxAge	long	No	The maximum cache time of dry run requests in the browser. Unit: seconds. Valid values: -1 to 172800.	1000
RuleConditions	array<object>	Yes	The configuration of the source IP-based forwarding rule.
	object	Yes	The IP addresses or CIDR blocks.
CookieConfig	object	No	The configurations of the cookies.
Values	array<object>	No	The cookie values.
	object	No	The value construct of the cookie.
Key	string	No	The key of the cookie. The key must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. The key can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
Value	string	No	The value of the cookie. The value must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. The value can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
HeaderConfig	object	No	The configuration of the header.
Key	string	No	The key of the header. The key must be 1 to 40 characters in length. It can contain lowercase letters, digits, hyphens (-), and underscores (_). Cookie and Host are not supported.	Port
Values	array	No	The value of the header.
	string	No	The value of the header. The header values within a forwarding rule must be unique. The value must be 1 to 128 characters in length. It can contain printable characters whose ASCII values are `greater than or equal to 32 and lower than 127`. You can use asterisks (*) and question marks (?) as wildcard characters. The header value cannot start or end with a space character.	5006
HostConfig	object	No	The configurations of the host.
Values	array	No	The hostname.
	string	No	The hostname. Each match condition of a forwarding rule can contain only one hostname. The hostname must be unique. The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, and the following special characters: - . * = ~ _ + \ ^ ! $ & \| ( ) [ ] ?. The hostname must contain at least one period (.) but cannot start or end with a period (.). The rightmost domain label can contain only letters and wildcards, and cannot contain digits or hyphens (-). The leftmost `domain label` can be an asterisk (). The domain labels cannot start or end with a hyphen (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters. If you enter a specific hostname or a wildcard hostname, the hostname cannot start with a tilde (~). If you enter a regular expression, the regular expression cannot start with an asterisk (*). The regular expression is not case-sensitive.	www.example.edu
MethodConfig	object	No	The configurations of the request methods.
Values	array	No	The request methods.
	string	No	The request methods. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE.	PUT
PathConfig	object	No	The configurations of the URLs.
Values	array	No	The path.
	string	No	The path. Valid values: The path must be 1 to 128 characters in length, and can contain asterisks () and question marks (?) as wildcards. The path is case-sensitive. If the URL path is not a regular expression, it must start with a forward slash (/) and can contain letters, digits, and the following special characters: `$ - _ .+ / & ~ @ : ' ?`. It cannot contain the following special characters: `" % # ; ! ( ) [ ] ^ , "`. You can use asterisks () and question marks (?) as wildcard characters. If the URL path is a regular expression, it must start with a tilde (~) and can contain letters, digits, and the following special characters: `. - _ / = ? ~ ^ $ : ( ) [ ] + \|`.	/test
QueryStringConfig	object	No	The configurations of the query strings.
Values	array<object>	No	The query strings.
	object	No	The query strings.
Key	string	No	The key of the query string. The key must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcards. The key can contain printable characters, except uppercase letters, space characters, and the following special characters: `# [ ] { } \ \| < > &`.	test
Value	string	No	The value of the query string. The value must be 1 to 128 characters in length. It can contain printable characters, except uppercase letters, space characters, and the following special characters: `# [ ] { } \ \| < > &`. You can use asterisks (*) and question marks (?) as wildcard characters.	test
Type	string	Yes	The type of forwarding rule. Valid values: Host: Requests are distributed based on hosts. Path: Requests are distributed based on paths. Header: Requests are distributed based on HTTP headers. QueryString: Requests are distributed based on query strings. Method: Requests are distributed based on request methods. Cookie: Requests are distributed based on cookies. SourceIp: Requests are distributed based on source IP addresses.	Host
SourceIpConfig	object	No	The configuration of the source IP-based forwarding rule. This parameter is required and takes effect only when Type is set to SourceIP.
Values	array	No	The configuration of the source IP-based forwarding rule.
	string	No	The IP addresses or CIDR blocks.	192.168.0.0/32
RuleName	string	Yes	The name of the forwarding rule. The name must be 2 to 128 characters in length. It can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter.	rule-doc

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF34B540750
RuleId	string	The forwarding rule ID.	rule-a3x3pg1yohq3lq****

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540750",
  "RuleId": "rule-a3x3pg1yohq3lq****"
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-01-18	The Error code has changed	View Change Details
2023-11-09	The Error code has changed	View Change Details

HTTP status code	Error code	Error message	Description
400	IncorrectStatus.Listener	The status of %s [%s] is incorrect.	The status of %s [%s] is incorrect.
400	OperationDenied.SameGroupForForwardAndMirrorAction	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	OperationDenied.IpGroupCanNotUsedForMirrorAction	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	OperationDenied.GRPCServerGroup	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	Conflict.Priority	There is already %s having the same configuration with %s.	There is already %s having the same configuration with %s.
400	ResourceQuotaExceeded.LoadBalancerRulesNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	ResourceQuotaExceeded.ServerGroupAttachedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s, usage %s/%s.
400	ResourceQuotaExceeded.LoadBalancerServersNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	ResourceQuotaExceeded.ServerAddedNum	The quota of %s is exceeded for resource %s, usage %s/%s.	The quota of %s is exceeded for resource %s. Usage: %s/%s.
400	QuotaExceeded.RuleWildcardsNum	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded, usage %s/%s.
400	QuotaExceeded.RuleMatchEvaluationsNum	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded. Usage: %s/%s.
400	QuotaExceeded.RuleActionsNum	The quota of %s is exceeded, usage %s/%s.	The quota of %s is exceeded. Usage: %s/%s.
400	Mismatch.Protocol	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	Mismatch.VpcId	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	OperationDenied.RewriteMissingForwardGroup	The operation is not allowed because of RewriteMissingForwardGroup.	The operation is not allowed because rewrite is missing the forward group.
400	ResourceInConfiguring.Listener	The specified listener is being configured, please try again later.	-
400	OperationDenied.MirrorActionSupportHttpGroupOnly	The operation is not allowed because of MirrorActionSupportHttpGroupOnly.	-
400	OperationDenied.ProtocolMustSameForForwardGroupAction	The operation is not allowed because of ProtocolMustSameForForwardGroupAction.	-
404	ResourceNotFound.Listener	The specified resource %s is not found.	The specified resource %s is not found.
404	ResourceNotFound.ServerGroup	The specified resource %s is not found.	The specified resource %s is not found.