Creates a forwarding rule for a specified listener.
Operation description
Note the following when you call this operation to create a forwarding rule:
-
When you configure a Redirect action, at least one parameter other than HttpCode must be set to a non-default value.
-
If you configure multiple actions for the same forwarding rule, a Rewrite action must be accompanied by a ForwardGroup action.
-
CreateRule is an asynchronous operation. After a request is sent, the system returns a request ID. The forwarding rule is not created immediately because the system creates it in the background. You can call ListRules to query the status of a forwarding rule:
If a forwarding rule is in the Provisioning state, it is being created.
If a forwarding rule is in the Available state, it has been created.
-
The maximum number of conditions (RuleConditions) and actions (RuleActions) that you can add to a forwarding rule are as follows:
Conditions: 5 for a Basic Edition instance, 10 for a Standard Edition instance, and 10 for a WAF-enabled instance.
Actions: 3 for a Basic Edition instance, 5 for a Standard Edition instance, and 5 for a WAF-enabled instance.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
alb:CreateRule |
create |
*LoadBalancer
*ServerGroup
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| ListenerId |
string |
Yes |
The ID of the Application Load Balancer (ALB) listener. |
lsn-l16uo9y****** |
| ClientToken |
string |
No |
A client token that is used to ensure the idempotence of the request. The client generates 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 RequestId of the request as the ClientToken. The RequestId of each API request is different. |
5A2CFF0E-5718-45B5-9D4D-70B****** |
| DryRun |
boolean |
No |
Specifies whether to perform a dry run. Valid values:
|
false |
| Priority |
integer |
Yes |
The priority of the rule. A smaller value indicates a higher priority. Valid values: 1 to 10000. Note
The priority of each rule within the same listener must be unique. |
10 |
| Direction |
string |
No |
The direction of the forwarding rule. Valid values:
Note
Basic Edition ALB instances do not support the Response type. |
Request |
| RuleActions |
array<object> |
Yes |
The actions of the forwarding rule. |
|
|
array<object> |
Yes |
The actions of the rule. |
||
| FixedResponseConfig |
object |
No |
The configuration of the fixed response. |
|
| Content |
string |
No |
The fixed response. The response can be up to 1 KB in size and can contain only ASCII characters. |
dssacav |
| ContentType |
string |
No |
The format of the fixed response. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. |
text/plain |
| HttpCode |
string |
No |
The HTTP status code of the response. You can specify a 2xx, 4xx, or 5xx status code. x is a digit. |
200 |
| ForwardGroupConfig |
object |
No |
The vServer groups to which requests are forwarded. You can specify up to five vServer groups. |
|
| ServerGroupTuples |
array |
No |
The vServer groups to which requests are forwarded. You can specify up to five vServer groups. |
|
|
object |
No |
The destination vServer group. |
||
| ServerGroupId |
string |
No |
The destination vServer group. |
sgp-k86c1ov501id6p**** |
| Weight |
integer |
No |
The weight. A larger value specifies a higher weight. More requests are forwarded to the vServer group with a higher weight. Valid values: 0 to 100.
|
100 |
| ServerGroupStickySession |
object |
No |
Session persistence for the vServer group. |
|
| Enabled |
boolean |
No |
Specifies whether to enable session persistence. Valid values:
|
false |
| Timeout |
integer |
No |
The timeout period. 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 to be inserted. The key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The key in InsertHeaderConfig cannot be the same as the key in another InsertHeaderConfig. Note
The following header keys are not supported (case-insensitive): |
key |
| Value |
string |
No |
The value of the header to be inserted.
|
UserDefined |
| ValueType |
string |
No |
The type of the header value. Valid values:
|
UserDefined |
| Order |
integer |
Yes |
The order of the action. Valid values: 1 to 50000. A smaller value indicates a higher priority. The value cannot be empty or the same for different actions. |
1 |
| RedirectConfig |
object |
No |
The configuration of the redirection. Note
You cannot set all parameters of RedirectConfig except httpCode to their default values. |
|
| Host |
string |
No |
The destination host to which requests are redirected. Valid values:
|
${host} |
| HttpCode |
string |
No |
The redirection method. Valid values: 301, 302, 303, 307, and 308. |
301 |
| Path |
string |
No |
The destination path to which requests are redirected. Valid values:
|
/test |
| Port |
string |
No |
The destination port to which requests are redirected.
|
10 |
| Protocol |
string |
No |
The destination protocol to which requests are redirected. Valid values:
Note
|
HTTP |
| Query |
string |
No |
The query string of the destination URL to which requests are redirected.
|
${query} |
| RewriteConfig |
object |
No |
The configuration of the rewrite. Note
If you configure multiple actions for the same forwarding rule, you must configure the ForwardGroup action type for the RewriteConfig action. |
|
| Host |
string |
No |
The destination host to which requests are rewritten. Valid values:
|
www.example.com |
| Path |
string |
No |
The destination path to which requests are rewritten. Valid values:
|
/tsdf |
| Query |
string |
No |
The query string of the destination URL to which requests are rewritten.
|
${query} |
| Type |
string |
Yes |
The action type. Valid values:
Note
A forwarding rule must contain a ForwardGroup (forward), Redirect (redirect), or FixedResponse (fixed response) action. When you use these actions with other types of actions, you must make sure that these actions are the last ones to be performed. |
ForwardGroup |
| TrafficLimitConfig |
object |
No |
The configuration of traffic throttling. |
|
| QPS |
integer |
No |
The number of queries per second (QPS). Valid values: 1 to 1000000. |
100 |
| PerIpQps |
integer |
No |
The QPS of a single IP address. Valid values: 1 to 1000000. Note
If you specify both the QPS and PerIpQps parameters, the value of PerIpQps must be smaller than the value of QPS. |
80 |
| TrafficMirrorConfig |
object |
No |
The configuration of traffic mirroring. |
|
| TargetType |
string |
No |
The destination to which traffic is mirrored. Valid values:
|
ForwardGroupMirror |
| MirrorGroupConfig |
object |
No |
The vServer group to which traffic is mirrored. |
|
| ServerGroupTuples |
array |
No |
The vServer group to which traffic is mirrored. |
|
|
object |
No |
The vServer group to which traffic is mirrored. |
||
| ServerGroupId |
string |
No |
The ID of the vServer group. |
sgp-00mkgijak0w4qgz9**** |
| RemoveHeaderConfig |
object |
No |
The configuration of the HTTP header to be removed. |
|
| Key |
string |
No |
The key of the header to be removed. The key must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The key cannot be used in another RemoveHeaderConfig.
|
test |
| CorsConfig |
object |
No |
The configuration of CORS. |
|
| AllowOrigin |
array |
No |
The allowed origins. You can specify only one asterisk (
|
|
|
string |
No |
The allowed origin. |
http://example.com |
|
| AllowMethods |
array |
No |
The allowed HTTP methods for cross-origin requests. |
|
|
string |
No |
The allowed HTTP method for cross-origin requests. Valid values:
|
GET |
|
| AllowHeaders |
array |
No |
The allowed headers for cross-origin requests. |
|
|
string |
No |
The allowed header. You can specify an asterisk ( |
test_123 |
|
| ExposeHeaders |
array |
No |
The headers that can be exposed. |
|
|
string |
No |
The header that can be exposed. You can specify an asterisk ( |
test_123 |
|
| AllowCredentials |
string |
No |
Specifies whether to allow credentials. Valid values:
|
on |
| MaxAge |
integer |
No |
The maximum cache time of preflight requests in the browser. Unit: seconds. Valid values: -1 to 172800. |
1000 |
| RuleConditions |
array<object> |
Yes |
The conditions of the forwarding rule. |
|
|
array<object> |
Yes |
The condition of the forwarding rule. |
||
| CookieConfig |
object |
No |
The configuration of the cookie. |
|
| Values |
array |
No |
The cookies. |
|
|
object |
No |
The cookie. |
||
| Key |
string |
No |
The key of the cookie.
|
test |
| Value |
string |
No |
The value of the cookie.
|
test |
| HeaderConfig |
object |
No |
The configuration of the header. |
|
| Key |
string |
No |
The key of the header.
|
Port |
| Values |
array |
No |
The header values. |
|
|
string |
No |
The HTTP header value. The header values cannot be the same in the same forwarding rule condition.
|
5006 |
|
| HostConfig |
object |
No |
The configuration of the host. |
|
| Values |
array |
No |
The hostnames. |
|
|
string |
No |
The hostname. You can specify only one hostname in a forwarding rule condition. The value cannot be the same as the value of another hostname.
|
www.example.edu |
|
| MethodConfig |
object |
No |
The configuration of the request method. |
|
| Values |
array |
No |
The request methods. |
|
|
string |
No |
The request method. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE. |
PUT |
|
| PathConfig |
object |
No |
The configuration of the forwarding path. |
|
| Values |
array |
No |
The forwarding paths. |
|
|
string |
No |
The forwarding path. Valid values:
|
/test |
|
| QueryStringConfig |
object |
No |
The configuration of the query string. |
|
| Values |
array |
No |
The query strings. |
|
|
object |
No |
The query string. |
||
| Key |
string |
No |
The key of the query string.
|
test |
| Value |
string |
No |
The value of the query string.
|
test |
| ResponseStatusCodeConfig |
object |
No |
The configuration of the response status code. |
|
| Values |
array |
No |
The response status codes. |
|
|
string |
No |
The response status code. |
test |
|
| ResponseHeaderConfig |
object |
No |
The configuration of the header condition. |
|
| Key |
string |
No |
The key of the header.
|
test |
| Values |
array |
No |
The header values. |
|
|
string |
No |
The header value.
|
50006 |
|
| Type |
string |
Yes |
The type of the forwarding rule. Valid values:
|
Host |
| SourceIpConfig |
object |
No |
The configuration of source IP-based traffic matching. This parameter is required and takes effect only when Type is set to SourceIP. |
|
| Values |
array |
No |
The source IP addresses for traffic matching. |
|
|
string |
No |
One or more IP addresses or CIDR blocks. |
192.168.0.0/32 |
|
| RuleName |
string |
Yes |
The name of the forwarding rule.
|
rule-doc |
| Tag |
array<object> |
No |
The tags. |
|
|
object |
No |
The tag. |
||
| 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 elements
|
Element |
Type |
Description |
Example |
|
object |
The returned data. |
||
| 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 ID of the forwarding rule. |
rule-a3x3pg1yohq3lq**** |
Examples
Success response
JSON format
{
"JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
"RequestId": "365F4154-92F6-4AE4-92F8-7FF34B540750",
"RuleId": "rule-a3x3pg1yohq3lq****"
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | IncorrectStatus.Listener | 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. | |
| 400 | Conflict.Priority | 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. | |
| 400 | ResourceQuotaExceeded.ServerGroupAttachedNum | 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. | |
| 400 | ResourceQuotaExceeded.ServerAddedNum | 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. | |
| 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. | |
| 404 | ResourceNotFound.ServerGroup | The specified resource %s is not found. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.