Creates a forwarding rule for a specified listener.
Operation description
When you call this operation to create a forwarding rule, take note of the following items:
-
When you configure a Redirect action, parameters other than HttpCode cannot all be set to default values.
-
When you configure multiple actions for a forwarding rule, the Rewrite action must be used together with the ForwardGroup action type.
-
The CreateRule operation is asynchronous. After a request is sent, the system returns an instance ID, but the forwarding rule may not be created yet. The system creates the forwarding rule in the background. You can call ListRules to query the creation status of the forwarding rule:
If the forwarding rule is in the Provisioning state, the forwarding rule is being created.
If the forwarding rule is in the Available state, the forwarding rule is created.
-
The maximum number of conditions (RuleConditions) and actions (RuleActions) that can be added to a forwarding rule is as follows:
Conditions: 5 for Basic Edition, 10 for Standard Edition, and 10 for WAF-enabled Edition.
Actions: 3 for Basic Edition, 5 for Standard Edition, and 5 for WAF-enabled Edition.
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 Balancing (ALB) instance listener. |
lsn-l16uo9y****** |
| 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 RequestId value as the ClientToken value. The RequestId value is different for each API request. |
5A2CFF0E-5718-45B5-9D4D-70B****** |
| DryRun |
boolean |
No |
Specifies whether to perform only a dry run, without performing the actual request. Valid values:
|
false |
| Priority |
integer |
Yes |
The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates a higher priority. Note
The priority of each rule within a listener must be unique. |
10 |
| Direction |
string |
No |
The direction of the forwarding rule. Valid values:
Note
ALB instances of Basic Edition do not support the Response type. |
Request |
| RuleActions |
array<object> |
Yes |
The list of forwarding rule actions. |
|
|
array<object> |
Yes |
The list of rule actions. |
||
| FixedResponseConfig |
object |
No |
The configuration of the fixed response. |
|
| Content |
string |
No |
The fixed content to return. The content can be up to 1 KB in size and can contain only ASCII characters. |
dssacav |
| ContentType |
string |
No |
The format of the fixed content. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. |
text/plain |
| HttpCode |
string |
No |
The HTTP response code to return. Only 2xx, 4xx, and 5xx numeric strings are supported, where x is any digit. |
200 |
| ForwardGroupConfig |
object |
No |
The list of destination server groups to which requests are forwarded. A maximum of 5 destination server groups can be added to a forwarding rule. |
|
| ServerGroupTuples |
array<object> |
No |
The list of destination server groups to which requests are forwarded. A maximum of 5 destination server groups can be added to a forwarding rule. |
|
|
object |
No |
The destination server group struct. |
||
| ServerGroupId |
string |
No |
The ID of the server group. |
sgp-k86c1ov501id6p**** |
| Weight |
integer |
No |
The weight of the server group. A server group with a higher weight receives more requests. Valid values: 0 to 100.
|
100 |
| ServerGroupStickySession |
object |
No |
The session persistence configuration between server groups. |
|
| Enabled |
boolean |
No |
Specifies whether to enable session persistence. Valid values:
|
false |
| Timeout |
integer |
No |
The timeout period, in seconds. Valid values: 1 to 86400. Default: 1000. |
100 |
| InsertHeaderConfig |
object |
No |
The configuration for inserting a header field. |
|
| Key |
string |
No |
The name of the header field to insert. The name must be 1 to 40 characters in length and can contain lowercase and uppercase letters a to z, digits, underscores (_), and hyphens (-). The header field name specified in InsertHeaderConfig must be unique. Note
You cannot set the header name to the following fields (case-insensitive): |
key |
| Value |
string |
No |
The value of the header field to insert.
|
UserDefined |
| ValueType |
string |
No |
The content type of the header field value. Valid values:
|
UserDefined |
| Order |
integer |
Yes |
The order in which the forwarding rule action is executed. Valid values: 1 to 50000. Actions are executed in ascending order of values. This parameter cannot be left empty and the value cannot be duplicated. |
1 |
| RedirectConfig |
object |
No |
The redirect configuration. Note
For the parameters in RedirectConfig, parameters other than httpCode cannot all use default values. |
|
| Host |
string |
No |
The host to which requests are redirected. Valid values:
|
${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:
|
/test |
| Port |
string |
No |
The port to which requests are redirected.
|
10 |
| Protocol |
string |
No |
The protocol to which requests are redirected. Valid values:
Note
|
HTTP |
| Query |
string |
No |
The query string to which requests are redirected.
|
${query} |
| RewriteConfig |
object |
No |
The rewrite configuration. Note
When you configure multiple actions for a forwarding rule, the RewriteConfig action must be used together with the ForwardGroup action type. |
|
| Host |
string |
No |
The destination hostname for internal redirection. Valid values:
|
www.example.com |
| Path |
string |
No |
The path to which requests are redirected. Valid values:
|
/tsdf |
| Query |
string |
No |
The query string for internal redirection.
|
${query} |
| Type |
string |
Yes |
The action type. Valid values:
Note
A forwarding rule must contain one ForwardGroup (forward to), Redirect (redirect), or FixedResponse (return a fixed response) action. When this action coexists with other action types, it must be executed last. |
ForwardGroup |
| TrafficLimitConfig |
object |
No |
The traffic throttling configuration. |
|
| QPS |
integer |
No |
The number of requests per second. Valid values: 1 to 1000000. |
100 |
| PerIpQps |
integer |
No |
The number of requests per second per IP address. Valid values: 1 to 1000000. Note
If you configure both the QPS and PerIpQps parameters, the value of PerIpQps must be smaller than the value of QPS. |
80 |
| TrafficMirrorConfig |
object |
No |
The traffic mirroring configuration. |
|
| TargetType |
string |
No |
The type of the mirror target. Valid values:
|
ForwardGroupMirror |
| MirrorGroupConfig |
object |
No |
The configuration for mirroring traffic to a server group. |
|
| ServerGroupTuples |
array<object> |
No |
The server groups to which traffic is mirrored. |
|
|
object |
No |
The server groups to which traffic is mirrored. |
||
| ServerGroupId |
string |
No |
The ID of the server group. |
sgp-00mkgijak0w4qgz9**** |
| RemoveHeaderConfig |
object |
No |
The configuration for removing an HTTP header field. |
|
| Key |
string |
No |
The name of the header field to remove. The name must be 1 to 40 characters in length and can contain uppercase and lowercase letters a to z, digits, underscores (_), and hyphens (-). The header field name cannot be duplicated in RemoveHeader.
|
test |
| CorsConfig |
object |
No |
The CORS configuration. |
|
| AllowOrigin |
array |
No |
The list of allowed origins. You can configure a single element
|
|
|
string |
No |
The allowed origin. |
http://example.com |
|
| AllowMethods |
array |
No |
The HTTP methods allowed for CORS requests. |
|
|
string |
No |
The HTTP method allowed for CORS requests. Valid values:
|
GET |
|
| AllowHeaders |
array |
No |
The list of headers allowed for CORS requests. |
|
|
string |
No |
The header allowed for CORS requests. You can set this to |
test_123 |
|
| ExposeHeaders |
array |
No |
The list of headers that can be exposed. |
|
|
string |
No |
The header that can be exposed. You can set this to |
test_123 |
|
| AllowCredentials |
string |
No |
Specifies whether credentials are allowed. Valid values:
|
on |
| MaxAge |
integer |
No |
The maximum cache time for preflight requests in the browser. Unit: seconds. Valid values: -1 to 172800. |
1000 |
| RuleConditions |
array<object> |
Yes |
The list of forwarding rule conditions. |
|
|
array<object> |
Yes |
The forwarding rule condition. |
||
| CookieConfig |
object |
No |
The cookie configuration. |
|
| Values |
array<object> |
No |
The list of cookie values. |
|
|
object |
No |
The cookie value struct. |
||
| Key |
string |
No |
The key of the cookie.
|
test |
| Value |
string |
No |
The value of the cookie.
|
test |
| HeaderConfig |
object |
No |
The header field configuration. |
|
| Key |
string |
No |
The header field key.
|
Port |
| Values |
array |
No |
The list of header field values. |
|
|
string |
No |
The HTTP header value list. Header field values within the same forwarding rule condition cannot be duplicated.
|
5006 |
|
| HostConfig |
object |
No |
The hostname configuration. |
|
| Values |
array |
No |
The list of hostnames. |
|
|
string |
No |
The hostname. Only one hostname can be specified in a forwarding rule condition, and the value cannot be duplicated.
|
www.example.edu |
|
| MethodConfig |
object |
No |
The request method configuration. |
|
| Values |
array |
No |
The list of request methods. |
|
|
string |
No |
The request method. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE. |
PUT |
|
| PathConfig |
object |
No |
The forwarding path configuration. |
|
| Values |
array |
No |
The list of forwarding paths. |
|
|
string |
No |
The forwarding path. Valid values:
|
/test |
|
| QueryStringConfig |
object |
No |
The query string configuration. |
|
| Values |
array<object> |
No |
The list of 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 response status code configuration. [_single.params.RuleConditions.items.ResponseStatusCodeConfig.Values. |
|
| Values |
array |
No |
The list of response status codes. |
|
|
string |
No |
The response status code. |
test |
|
| ResponseHeaderConfig |
object |
No |
The response header configuration. |
|
| Key |
string |
No |
The header field key.
|
test |
| Values |
array |
No |
The list of header field values. |
|
|
string |
No |
The header field value.
|
50006 |
|
| Type |
string |
Yes |
The type of the forwarding rule. Valid values:
|
Host |
| SourceIpConfig |
object |
No |
The configuration for source IP-based service traffic matching. This parameter is required and takes effect only when Type is set to SourceIP. |
|
| Values |
array |
No |
The list of source IP addresses for service 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 list of tags. |
|
|
object |
No |
The tag structure. |
||
| Key |
string |
No |
The tag key. The tag key can be up to 128 characters in length and cannot start with aliyun or acs:. It cannot contain http:// or https://. |
env |
| Value |
string |
No |
The tag value. The tag value can be up to 128 characters in length and cannot start with aliyun or acs:. It cannot contain http:// or https://. |
product |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response struct. |
||
| JobId |
string |
The asynchronous task ID. |
72dcd26b-f12d-4c27-b3af-18f6aed5**** |
| RequestId |
string |
The request ID. |
365F4154-92F6-4AE4-92F8-7FF34B540750 |
| RuleId |
string |
The forwarding rule ID. |
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.