Creates a forwarding rule under a specified listener.
Operation description
When you call this operation to create a forwarding rule, note the following items:
-
When you configure the Redirect action, you cannot set all parameters except the HttpCode parameter to their default values.
-
When you configure multiple actions for the same forwarding rule, you must set the action type of the Rewrite action to ForwardGroup.
-
The CreateRule operation is asynchronous. After you send the request, the system returns an instance ID, but the forwarding rule is not yet created and the creation node in the background is still in progress. You can invoke the ListRules operation 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 you can add to a forwarding rule varies based on the edition:
Number of conditions: 5 for Basic Edition, 10 for Standard Edition, and 10 for WAF-enhanced Edition.
Number of actions: 3 for Basic Edition, 5 for Standard Edition, and 5 for WAF-enhanced 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 listener on the Application Load Balancing (ALB) instance. |
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 value, but you must make sure that the value is unique among different requests. The client token can contain only ASCII characters. Note
If you do not set this parameter, the system automatically uses the RequestId of the API request as the ClientToken. The RequestId of each API request is different. |
5A2CFF0E-5718-45B5-9D4D-70B****** |
| DryRun |
boolean |
No |
Specifies whether to perform only a dry run. Valid values:
|
false |
| Priority |
integer |
Yes |
The priority of the rule. Valid values: 1 to 10000. A smaller value indicates a higher priority. 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
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 fixed response content configuration. |
|
| Content |
string |
No |
The fixed content to return. The maximum size is 1 KB. Only ASCII characters are supported. |
dssacav |
| ContentType |
string |
No |
The format of the fixed content to return. Valid values: text/plain, text/css, text/html, application/javascript, and application/json. |
text/plain |
| HttpCode |
string |
No |
The HTTP status code to return. Only numeric strings in the format of 2xx, 4xx, or 5xx are supported, where x represents any digit. |
200 |
| ForwardGroupConfig |
object |
No |
The list of destination server groups to which requests are forwarded. You can add up to five destination server groups in a forwarding rule. |
|
| ServerGroupTuples |
array<object> |
No |
The list of destination server groups to which requests are forwarded. You can add up to five destination server groups in a forwarding rule. |
|
|
object |
No |
The destination server group structure. |
||
| ServerGroupId |
string |
No |
The destination server group to which requests are forwarded. |
sgp-k86c1ov501id6p**** |
| Weight |
integer |
No |
The weight. A greater value indicates a higher weight, which means that more requests are forwarded to the server group. Valid values: 0 to 100.
|
100 |
| ServerGroupStickySession |
object |
No |
The session persistence configuration across server groups. |
|
| 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 for inserting an HTTP header. |
|
| Key |
string |
No |
The name of the header to insert. The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Header names in InsertHeaderConfig must be unique. Note
You cannot set the header name to any of the following fields (case-insensitive): |
key |
| Value |
string |
No |
The value of the header to insert.
|
UserDefined |
| ValueType |
string |
No |
The content type of the header field. Valid values:
|
UserDefined |
| Order |
integer |
Yes |
The execution order of the forwarding rule action. Valid values: 1 to 50000. Actions are executed in ascending order of their values. The value cannot be empty and must be unique. |
1 |
| RedirectConfig |
object |
No |
The redirect configuration. Note
For the parameters in RedirectConfig, you cannot use default values for all parameters except HttpCode. |
|
| Host |
string |
No |
The host to which requests are redirected. Valid values:
|
${host} |
| HttpCode |
string |
No |
The HTTP status code for the redirect. 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. Valid values:
|
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. Valid values:
|
${query} |
| RewriteConfig |
object |
No |
The rewrite configuration. Note
If multiple actions are configured in the same forwarding rule, the RewriteConfig action must be used together with the ForwardGroup action type. |
|
| Host |
string |
No |
The destination host for the internal rewrite. 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 the internal rewrite. Valid values:
|
${query} |
| Type |
string |
Yes |
The action type. Valid values:
Note
A forwarding rule must contain at least one ForwardGroup, Redirect, or FixedResponse action. If it is used together with other action types, it must be executed last. |
ForwardGroup |
| TrafficLimitConfig |
object |
No |
The traffic throttling configuration. |
|
| QPS |
integer |
No |
The number of queries per second (QPS). Valid values: 1 to 1000000. |
100 |
| PerIpQps |
integer |
No |
The number of queries per second from a single IP address. Valid values: 1 to 1000000. Note
If the QPS parameter is also configured, the value of PerIpQps must be less than the value of QPS. |
80 |
| TrafficMirrorConfig |
object |
No |
The traffic mirroring configuration. |
|
| TargetType |
string |
No |
The target type for traffic mirroring. Valid values:
|
ForwardGroupMirror |
| MirrorGroupConfig |
object |
No |
The configuration for mirroring traffic to a server group. |
|
| ServerGroupTuples |
array<object> |
No |
The configuration for mirroring traffic to a server group. |
|
|
object |
No |
The configuration for mirroring traffic to a server group. |
||
| ServerGroupId |
string |
No |
The ID of the server group. |
sgp-00mkgijak0w4qgz9**** |
| RemoveHeaderConfig |
object |
No |
The configuration for removing an HTTP header. |
|
| Key |
string |
No |
The name of the header to remove. The name must be 1 to 40 characters in length and can contain letters, digits, underscores (_), and hyphens (-). Header names in RemoveHeader must be unique.
|
test |
| CorsConfig |
object |
No |
The CORS configuration. |
|
| AllowOrigin |
array |
No |
The list of allowed origins. You can specify a single 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 list of allowed cross-origin headers. |
|
|
string |
No |
The allowed cross-origin header. You can specify an asterisk ( |
test_123 |
|
| ExposeHeaders |
array |
No |
The list of exposed headers. |
|
|
string |
No |
The exposed header. 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 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 structure. |
||
| Key |
string |
No |
The cookie key.
|
test |
| Value |
string |
No |
The cookie value.
|
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. Header field values within the same forwarding rule condition cannot be duplicated.
|
5006 |
|
| HostConfig |
object |
No |
The host configuration. |
|
| Values |
array |
No |
The list of hostnames. |
|
|
string |
No |
The hostname. A forwarding rule condition can contain only one hostname, and the values 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 query string key.
|
test |
| Value |
string |
No |
The query string value.
|
test |
| ResponseStatusCodeConfig |
object |
No |
The response status code configuration. |
|
| Values |
array |
No |
The list of response status codes. |
|
|
string |
No |
The response status code. |
test |
|
| ResponseHeaderConfig |
object |
No |
The header condition 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 forwarding rule type. Valid values:
|
Host |
| SourceIpConfig |
object |
No |
The source IP-based service traffic matching configuration. Required and valid only when Type is set to SourceIP. |
|
| Values |
array |
No |
The list of source IP-based service traffic matching conditions. |
|
|
string |
No |
The IP address or CIDR block. |
192.168.0.0/32 |
|
| RuleName |
string |
Yes |
The forwarding rule name.
|
rule-doc |
| Tag |
array<object> |
No |
The list of tags. |
|
|
object |
No |
The tag structure. |
||
| Key |
string |
No |
The tag key. Can be up to 128 characters in length. Cannot start with |
env |
| Value |
string |
No |
The tag value. Can be up to 128 characters in length. Cannot start with |
product |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response data structure. |
||
| 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. | This operation is not supported in the listener's current state. |
| 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 denied because a listener bound to this gRPC server group does not have HTTP/2.0 enabled. |
| 400 | Conflict.Priority | There is already %s having the same configuration with %s. | Priority conflict. A configuration with the same priority already exists. |
| 400 | ResourceQuotaExceeded.LoadBalancerRulesNum | The quota of %s is exceeded for resource %s, usage %s/%s. | The number of forwarding rules has exceeded the quota limit. |
| 400 | ResourceQuotaExceeded.ServerGroupAttachedNum | The quota of %s is exceeded for resource %s, usage %s/%s. | The number of associations allowed for the server group exceeds the quota limit. |
| 400 | ResourceQuotaExceeded.LoadBalancerServersNum | The quota of %s is exceeded for resource %s, usage %s/%s. | The number of backend servers has exceeded the quota limit. |
| 400 | ResourceQuotaExceeded.ServerAddedNum | The quota of %s is exceeded for resource %s, usage %s/%s. | The number of servers added to the server group exceeds the quota limit. |
| 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 number of forwarding rule conditions has exceeded the quota limit. |
| 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. | The resource %s is being modified. Try again later. |
| 400 | OperationDenied.MirrorActionSupportHttpGroupOnly | The operation is not allowed because of MirrorActionSupportHttpGroupOnly. | The operation is rejected because traffic mirroring actions support only HTTP-type server groups. |
| 400 | OperationDenied.ProtocolMustSameForForwardGroupAction | The operation is not allowed because of ProtocolMustSameForForwardGroupAction. | The operation is forbidden because the protocol must be the same. |
| 404 | ResourceNotFound.Listener | The specified resource %s is not found. | The listener does not exist. |
| 404 | ResourceNotFound.ServerGroup | The specified resource %s is not found. | The backend server group does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.