CreateRules - Server Load Balancer - Alibaba Cloud Documentation Center

Creates one or more forwarding rules at a time.

Operation description

When you call this operation, take note of the following limits:

When you configure the Redirect action, you can use the default value for the HttpCode parameter but you cannot use the default values for all of the other parameters.
If you specify the Rewrite action and other actions in a forwarding rule, make sure that one of the actions is ForwardGroup.
CreateRules 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 forwarding rules.
- If forwarding rules are in the Provisioning state, the forwarding rules are being created.
- If forwarding rules are in the Available state, the forwarding rules have been created.
You can set RuleConditions and RuleActions to add conditions and actions to a forwarding rule. Take note of the following limits on the number of conditions and the number of actions in each forwarding rule:
- Limits on conditions: You can specify at most 5 conditions if you use a basic Application Load Balancer (ALB) instance, at most 10 conditions if you use a standard ALB instance, and at most 10 conditions if you use a WAF-enabled ALB instance.
- Limits on actions: You can specify at most 3 actions if you use a basic ALB instance, at most 5 actions if you use a standard ALB instance, and at most 10 actions if you use 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 ID of the Application Load Balancer (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 sends the request. If the request passes the dry run, a `2xx HTTP` status code is returned and the operation is performed.	false
Rules	array<object>	Yes	The forwarding rules. You can specify at most 10 forwarding rules in each request.
	object	Yes	The IP addresses or CIDR blocks. You can specify at most five values for SourceIp.
Priority	integer	Yes	The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority. You can specify at most 10 priorities. Note The priorities of forwarding rules for the same listener must be unique.	10
RuleActions	array<object>	Yes	The actions of the forwarding rule.
	object	Yes
FixedResponseConfig	object	No	The configuration of the custom response. You can specify at most 20 custom responses.
Content	string	No	The content of the custom response. The content cannot exceed 1 KB in size, and can contain only ASCII characters.	dssacav
ContentType	string	No	The format of the content. Valid values: text/plain text/css text/html application/javascript application/json	text/plain
HttpCode	string	No	The HTTP status code in responses. Valid values: 2xx, 4xx, 5xx. The value must be a numeric string. x must be a digit.	HTTP_200
ForwardGroupConfig	object	No	The configuration of the server group. You can specify at most 20 server groups.
ServerGroupTuples	array<object>	No	The server groups to which requests are forwarded.
	object	No
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 the number of destination server groups is 1, the default weight of the server group is 100, unless you specify a weight. If the number of destination server groups is larger than 1, you must specify a weight.	100
ServerGroupStickySession	object	No	The configuration of session persistence for the 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.	2
InsertHeaderConfig	object	No	The key of the header to be inserted. You can specify at most 20 headers.
Key	string	No	The key of the header. The header key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header keys specified by InsertHeaderConfig must be unique. Note The following header keys are not supported: `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`. The header keys are not case-sensitive.	key
Value	string	No	The value of the header to be inserted. If ValueType is set to SystemDefined, you can set the Value parameter to one of the following values: ClientSrcPort: the client port. ClientSrcIp: the IP address of the client. Protocol: the request protocol (HTTP or HTTPS). SLBId: the ID of the ALB instance. SLBPort: the listener 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 wildcard characters, such as asterisks () and question marks (?), and printable characters whose ASCII values are `larger than or equal to 32 and smaller than 127`. The header value cannot start or end with a space character. If ValueType* is set to ReferenceHeader, you can reference a value from request headers. The value must be 1 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), and underscores (_).	UserDefined
ValueType	string	No	The type of the header. Valid values: UserDefined: a custom header ReferenceHeader: a header that references one of the request headers SystemDefined: a system-defined header	UserDefined
Order	integer	Yes	The priority of the action. Valid values: 1 to 50000. A lower value indicates a higher priority. The actions of a forwarding rule are applied in descending order of priority. This parameter cannot empty. The priority of each action within a forwarding rule must be unique. You can specify at most 20 action priorities.	1
RedirectConfig	object	No	The redirect configuration. You can specify at most 20 redirects.
Host	string	No	The hostname to which requests are forwarded. Valid values: ${host} (default): If ${host} is returned, no other character is appended. The hostname must meet the following requirements: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (), and question marks (?). 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 wildcard characters. It does not contain digits or hyphens (-). The domain labels cannot start or end with a hyphen (-). You can place an asterisk () or a question mark (?) anywhere in a domain label as wildcard characters.	www.example.com
HttpCode	string	No	The redirect type. Valid values: 301, 302, 303, 307, and 308.	301
Path	string	No	The URL 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. The path must meet the following requirements: The URL must be 1 to 128 characters in length. The URL 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. The URL is case-sensitive.	/test
Port	string	No	The port to which requests are distributed. ${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 ${protocol} is returned, no other character is appended. HTTP or HTTPS Note HTTPS listeners supports only 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. The preceding variables can be used at the same time or combined with a custom value. The query string must meet the following requirements: The query string must be 1 to 128 characters in length. The query string can contain printable characters, but cannot contain space characters, the special characters `# [ ] { } \ \| < > &`, or uppercase letters.	quert
RewriteConfig	object	No	The rewrite configuration. You can specify at most 20 rewrites.
Host	string	No	The hostname to which requests are rewritten. Valid values: ${host} (default): If you set the value to ${host}, you cannot append other characters. The hostname must meet the following requirements: The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (), and question marks (?). 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 wildcard characters. It does not contain digits or hyphens (-). The domain labels cannot start or end with hyphens (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	www.example.com
Path	string	No	The URL 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. The URL must meet the following requirements: The value must be 1 to 128 characters in length, The URL 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. The URL is case-sensitive.	/tsdf
Query	string	No	The query string of the URL to which requests are rewritten. Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value. The query string must meet the following requirements: The query string must be 1 to 128 characters in length. The query string can contain printable characters, but cannot contain space characters, the special characters `# [ ] { } \ \| < > &`, or uppercase letters.	quedsa
Type	string	Yes	The action type. You can specify at most 11 types of action. Valid values: ForwardGroup: distributes requests to multiple vServer groups. Redirect: redirects requests. FixedResponse: returns a custom response. Rewrite: rewrites requests. InsertHeader: inserts headers. RemoveHeaderConfig: deletes a header. TrafficLimit: throttles traffic. TrafficMirror: mirrors network traffic. Cors: enables cross-origin resource sharing (CORS). You can specify the last action and the actions that you want to perform before the last action: FinalType: Each forwarding rule can contain only one FinalType action, which is performed at the end. You can specify only one of ForwardGroup, Redirect, and FixedResponse. ExtType: Each forwarding rule can contain one or more ExtType actions, which are performed before the FinalType action. If you want to specify an ExtType action, you must also specify a FinalType action. You can specify multiple InsertHeader actions or one Rewrite action.	ForwardGroup
TrafficLimitConfig	object	No	The configuration of traffic throttling. You can specify at most 20 traffic throttling rules.
QPS	integer	No	The queries per second (QPS). Value range: 1 to 1000000.	100
PerIpQps	integer	No	The number of requests per IP address. Value range: 1 to 1000000. Note If both the QPS and PerIpQps parameters are specified, the value of the QPS parameter is smaller than the value of the PerIpQps parameter.	80
TrafficMirrorConfig	object	No	The configuration of traffic mirroring. You can specify at most 20 traffic mirroring rules.
TargetType	string	No	The type of target to which network traffic is mirrored. Valid values: ForwardGroupMirror: a server group.	ForwardGroupMirror
MirrorGroupConfig	object	No	The configuration of the server group to which traffic is mirrored.
ServerGroupTuples	array<object>	No	The server group to which traffic is mirrored.
	object	No
ServerGroupId	string	No	The server group ID.	srg-00mkgijak0w4qgz9****
RemoveHeaderConfig	object	No	The HTTP header to be removed.
Key	string	No	The key of the header to be removed. The header key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header keys specified in RemoveHeader must be unique. If Direction is set to Request, the following header keys are not supported: `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`. The header keys are not case-sensitive. If Direction is set to Response, the following header keys are not supported: `connection`, `upgrade`, `content-length`, and `transfer-encoding`. The header keys are not case-sensitive.	test
CorsConfig	object	No	The CORS configuration.
AllowOrigin	array	No	The trusted origins of CORS requests. One or more values are supported. Asterisks (``) can be used as wildcard characters. Each value must start with `http://` or `https://`, which must be followed by a valid domain name, including top-level domain names. Example: `http://.test.abc.example.com`. You can specify a port in each value or leave the port empty. Valid values: 1 to 65535.
	string	No	The allowed origins of CORS requests.	http://example.com
AllowMethods	array	No	The trusted HTTP methods of CORS requests.
	string	No	The trusted HTTP method of CORS requests. Valid values: GET POST PUT DELETE HEAD OPTIONS PATCH	GET
AllowHeaders	array	No	The trusted headers of CORS requests.
	string	No	The headers that can be exposed. One or more values are supported. Asterisks (`*`) can be used as wildcard characters. Multiple values are separated by commas (,). Each value can be up to 32 characters in length, and can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-).	test_123
ExposeHeaders	array	No	The headers that can be exposed.
	string	No	The header that can be exposed. One or more values are supported. Asterisks (`*`) can be used as wildcard characters. Multiple values are separated by commas (,). Each value can be up to 32 characters in length, and can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-).	test_123
AllowCredentials	string	No	Specifies whether to allow credentials to be carried in CORS requests. Valid values: on off	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 conditions of the forwarding rule.
	object	Yes
CookieConfig	object	No	The key-value pairs of the cookie. You can specify at most 20 cookies.
Values	array<object>	No	The cookie value.
	object	No
Key	string	No	The cookie key. The cookie key must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. It can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
Value	string	No	The cookie value. The cookie value must be 1 to 100 characters in length. You can use asterisks (*) and question marks (?) as wildcard characters. It can contain printable characters, except uppercase letters, space characters, and the following special characters: `; # [ ] { } \ \| < > &`.	test
HeaderConfig	object	No	The configuration of the header. You can specify at most 20 headers.
Key	string	No	The key of the header. The header key must be 1 to 40 characters in length, The header key can contain 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 header value must be 1 to 128 characters in length. The header value can contain asterisks (*), question marks (?), and other printable characters whose ASCII values are `larger than or equal to 32 and smaller than 127`. The value cannot start or end with a space character.	5006
HostConfig	object	No	The configuration of the hosts. You can specify at most 20 hosts.
Values	array	No	The hostname.
	string	No	The hostname. A forwarding rule can contain only one unique hostname. The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (), and question marks (?). The hostname contains at least one period (.) but does not start or end with a period (.). The rightmost domain label can contain only letters and wildcard characters. It does not contain digits or hyphens (-). The domain labels do not start or end with hyphens (-). You can use asterisks () and question marks (?) anywhere in a domain label as wildcard characters.	www.example.com
MethodConfig	object	No	The configurations of the request methods. You can specify at most 20 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 forwarding URLs. You can specify at most 20 forwarding URLs.
Values	array	No	The URLs to which requests are forwarded.
	string	No	The URL to which requests are forwarded. The URL must meet the following requirements: The URL must be 1 to 128 characters in length. The URL 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. The URL is case-sensitive.	/test
QueryStringConfig	object	No	The configuration of the query conditions. You can specify at most 20 query conditions.
Values	array<object>	No	The configurations of the query string.
	object	No
Key	string	No	They 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, excluding 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, The value can contain printable characters, excluding uppercase letters, space characters, and the following special characters: `# [ ] { } \ \| < > &`. You can use asterisks (*) and question marks (?) as wildcard characters.	test
ResponseHeaderConfig	object	No	The configuration of the header. You can specify at most 20 headers.
Key	string	No	The key of the header. The header key must be 1 to 40 characters in length. It can contain 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 value must be 1 to 128 characters in length, The header value can contain printable characters whose ASCII values are `larger than or equal to 32 and smaller than 127`, lowercase letters, asterisks (*), and question marks (?). The value cannot start or end with a space character.	5006
ResponseStatusCodeConfig	object	No	The configurations of the response status codes.
Values	array	No	The response status codes.
	string	No	The response status code.	200
Type	string	Yes	The type of forwarding rule. You can specify at most seven types of forwarding rules. Valid values: Host: Requests are forwarded based on hosts. Path: Requests are forwarded based on URLs. Header: Requests are forwarded based on HTTP headers. QueryString: Requests are forwarded based on query strings. Method: Requests are forwarded based on request methods. Cookie: Requests are forwarded based on cookies. SourceIp: Requests are forwarded based on source IP addresses. ResponseHeader: Requests are forwarded based on HTTP response headers. ResponseStatusCode: Requests are forwarded based on response status codes.	Host
SourceIpConfig	object	No	Traffic matching based on source IP addresses. This parameter is required and valid when Type is set to SourceIP. You can specify up to five IP addresses or CIDR blocks in the SourceIpConfig parameter.
Values	array	No	Traffic matching based on source IP addresses.
	string	No	You can specify one or more IP addresses, including CIDR blocks. You can specify up to five IP addresses or CIDR blocks in the SourceIpConfig parameter.	192.168.0.0/32
RuleName	string	Yes	The name of the forwarding rule. You can specify at most 20 rule names. The name must be 2 to 128 characters in length. The name can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter.	test
Direction	string	No	The direction to which the forwarding rule is applied. You can specify only one direction. Valid values: Request (default): The forwarding rule applies to requests. Requests sent from clients to ALB are matches against the match conditions and processed based on the rule actions. Response: The forwarding rule applies to responses. Responses from backend servers to ALB are matches against the match conditions and processed based on the rule actions. Note Basic ALB instances do not support forwarding rules applied to the Response direction.	Request
Tag	array<object>	No	The tag that you want to add.
	object	No
Key	string	No	The tag key. The tag key can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://.	env
Value	string	No	The tag value. The tag value can be up to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://.	product

Response parameters

Parameter	Type	Description	Example
	object	Creates one or more forwarding rules at a time.
JobId	string	The ID of the asynchronous task.	72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF34B540710
RuleIds	array<object>	The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority. Note The priorities of the forwarding rules created for the same listener is unique.
	object
RuleId	string	The forwarding rule ID.	rule-a3x3pg1yohq3lq****
Priority	integer	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

Examples

Sample success responses

JSONformat

{
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540710",
  "RuleIds": [
    {
      "RuleId": "rule-a3x3pg1yohq3lq****",
      "Priority": 10
    }
  ]
}

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.IpGroupCanNotUsedForMirrorAction	The operation is not allowed because of %s.	The operation is not allowed because of %s.
400	OperationDenied.SameGroupForForwardAndMirrorAction	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.VpcId	The %s is mismatched for %s and %s.	The %s is mismatched for %s and %s.
400	Mismatch.Protocol	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	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.