Creates one or more forwarding rules.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateRules

The operation that you want to perform. Set the value to CreateRules.

ListenerId String Yes lsr-bp1bpn0kn908w4nbw****

The ID of the listener added to the Application Load Balancer (ALB) instance.

ClientToken String No 5A2CFF0E-5718-45B5-9D4D-70B3FF3898

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 ensure that it is unique among different requests. ClientToken can contain only ASCII characters.

Note If you do not set this parameter, the system uses RequestId as ClientToken. RequestId may be different for each API request.
DryRun Boolean No true

Specifies whether to only precheck this request. Valid values:

  • true: prechecks the request without creating the resource. The system prechecks the required parameters, request syntax, and limits. If the request fails to pass the precheck, an error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false: prechecks the request. If the request passes the precheck, the system returns an HTTP 2xx status code and performs the operation. This is the default value.
Rules Array Yes

The list of forwarding rules. You can specify at most 10 forwarding rules in each request.

Priority Integer Yes 10

The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority.

Note The priority of each forwarding rule within a listener must be unique.
RuleActions Array Yes

The actions of the forwarding rule.

FixedResponseConfig Object No

The configuration of the custom response.

Content String No dssacav

The content of the custom response. The content cannot exceed 1 KB in size and can contain only ASCII characters.

ContentType String No text/plain

The content type. Valid values:

  • text/plain
  • text/css
  • text/html
  • application/javascript
  • application/json
HttpCode String No HTTP_200

The HTTP status code in the response. Valid values: HTTP_2xx, HTTP_4xx, and HTTP_5xx. x must be a digit.

ForwardGroupConfig Object No

The configuration of the server group.

ServerGroupTuples Array No

The list of server groups to which requests are forwarded.

ServerGroupId String No sgp-k86c1ov501id6p****

The server group to which requests are forwarded.

Weight Integer No 100

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. Default value: 100.

ServerGroupStickySession Object No

The configuration of session persistence for server groups.

Enabled Boolean No false

Specifies whether to enable session persistence. Valid values:

  • true: enables session persistence.
  • false (default): disables session persistence.
Timeout Integer No 2

The timeout period. Unit: seconds. Valid values: 1 to 86400.

InsertHeaderConfig Object No

The configuration of the header to be inserted.

Key String No key

The key of the header. The key must be 1 to 40 characters in length, and can contain lowercase letters, digits, underscores (_), and hyphens (-). The header key specified by InsertHeaderConfig must be unique.

Note You cannot set one of 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.
Value String No UserDefined

The value of the header to be inserted.

  • If ValueType is set to SystemDefined, you can set 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 (-).
ValueType String No UserDefined

The type of the header. Valid values:

  • UserDefined: a custom header
  • ReferenceHeader: references one of the request headers.
  • SystemDefined: a header predefined by the system
Order Integer Yes 1

The priority of the action. Valid values: 1 to 50000. A lower value specifies 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.

RedirectConfig Object No

The configuration of the redirect action.

Host String No www.example.com

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, hyphens (-), and periods (.). You can use asterisks (*) and question marks (?) as wildcards.
    • 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 cannot contain digits or hyphens (-).
    • The domain labels cannot start or end with hyphens (-).
    • You can use an asterisk (*) and question mark (?) anywhere in a domain label as wildcards.
HttpCode String No 301

The redirect type. Valid values: 301, 302, 303, 307, and 308.

Path String No /test

The path to which requests are redirected. Valid values:

  • Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable cannot be specified more than once. You can specify one or more of the preceding variables in each request. You can also combine them with the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • It must be 1 to 128 characters in length.
    • 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 wildcards.
    • The value is case-sensitive.
Port String No 10

The port to which requests are redirected.

  • ${port} (default): If you set the value to ${port}, you cannot append other characters.
  • Other valid values: 1 to 63335.
Protocol String No HTTP

The redirect protocol. Valid values:

  • ${protocol} (default): If you set the value to ${protocol}, you cannot append other characters.
  • You can set the protocol to HTTP or HTTPS.
Note HTTPS listeners do not support HTTPS to HTTP redirects.
Query String No quert

The query string of the URL to which requests are redirected.

  • Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable cannot be specified more than once. You can specify one or more of the preceding variables in each request. You can also combine them with the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • It must be 1 to 128 characters in length.
    • It can contain printable characters, excluding space characters, the special characters # [ ] { } \ | < > &, and uppercase letters.
RewriteConfig Object No

The configuration of the rewrite action.

Host String No www.example.com

The hostname to which requests are forwarded. 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, hyphens (-), and periods (.). You can use asterisks (*) and question marks (?) as wildcards.
    • 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 cannot contain digits or hyphens (-).
    • The domain labels cannot start or end with hyphens (-). You can use an asterisk (*) and question mark (?) anywhere in a domain label as wildcards.
Path String No /tsdf

The path to which requests are forwarded. Valid values:

  • Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. Each variable cannot be specified more than once. You can specify one or more of the preceding variables in each request. You can also combine them with the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • It must be 1 to 128 characters in length.
    • 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 wildcards.
    • The value is case-sensitive.
Query String No quedsa

The query string of the URL to which requests are forwarded.

  • Default value: ${query}. ${host}, ${protocol}, and ${port} are also supported. Each variable cannot be specified more than once. You can specify one or more of the preceding variables in each request. You can also combine them with the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • It must be 1 to 128 characters in length.
    • It can contain printable characters, excluding space characters, the special characters # [ ] { } \ | < > &, and uppercase letters.
Type String Yes ForwardGroup

The action. 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 network traffic.

You can specify the last action and the actions that you want to perform before the last action:

  • FinalType: the last action to be performed in a forwarding rule. Each forwarding rule can contain only one FinalType action. You can specify a ForwardGroup, Redirect, or FixedResponse action as the FinalType action.
  • ExtType: the action 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.
TrafficLimitConfig Object No

The action to throttle traffic.

QPS Integer No 100

Queries per second (QPS). Valid values: 1 to 100000.

TrafficMirrorConfig Object No

The action to mirror traffic.

TargetType String No ForwardGroupMirror

The type of destination to which network traffic is mirrored.

MirrorGroupConfig Object No

The list of server groups to which network traffic is mirrored.

ServerGroupTuples Array No

The server group to which network traffic is mirrored.

ServerGroupId String No srg-00mkgijak0w4qgz9****

The ID of the vServer group.

RuleConditions Array Yes

The conditions of the forwarding rule.

CookieConfig Object No

The configurations of the cookies.

Values Array No

The key-value pairs of cookies.

Key String No test

The key of the cookie.

  • It must be 1 to 100 characters in length.
  • You can use asterisks (*) and question marks (?) as wildcards.
  • It can contain printable characters, excluding uppercase letters, space characters, and the following special characters: ; # [ ] { } \ | < > &.
Value String No test

The value of the cookie.

  • It must be 1 to 100 characters in length.
  • You can use asterisks (*) and question marks (?) as wildcards.
  • It can contain printable characters, excluding uppercase letters, space characters, and the following special characters: ; # [ ] { } \ | < > &.
HeaderConfig Object No

The configuration of the header.

Key String No Port

The key of the header.

  • The key must be 1 to 40 characters in length.
  • It can contain lowercase letters, digits, hyphens (-), and underscores (_).
  • You cannot specify Cookie or Host.
Values Array of String No 5006

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. For example, asterisks (*), question marks (?).
  • The header value cannot start or end with a space character.
HostConfig Object No

The configurations of the hosts.

Values Array of String No www.example.com

The hostnames. A forwarding rule can contain only one and 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 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 cannot contain digits or hyphens (-).
  • The domain labels cannot start or end with hyphens (-). You can use an asterisk (*) and question mark (?) anywhere in a domain label as wildcards.
MethodConfig Object No

The configurations of the request methods.

Values Array of String No PUT

The request methods. Valid values: HEAD, GET, POST, OPTIONS, PUT, PATCH, and DELETE.

PathConfig Object No

The configurations of the URLs.

Values Array of String No /test

The paths. Limits:

  • It must be 1 to 128 characters in length.
  • 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 wildcards.
  • The value is case-sensitive.
QueryStringConfig Object No

The configuration of the query string.

Values Array No

The key-value pairs in the query string.

Key String No test

They key of the query string.

  • It 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: # [ ] { } \ | < > &).
Value String No test

The value of the query string.

  • It must be 1 to 128 characters in length.
  • It can contain printable characters (excluding uppercase letters, space characters, and the following special characters: # [ ] { } \ | < > &). You can use asterisks (*) and question marks (?) as wildcards.
ResponseHeaderConfig Object No

The configuration of the header.

Key String No Port

The key of the header.

  • The key must be 1 to 40 characters in length.
  • It can contain lowercase letters, digits, hyphens (-), and underscores (_).
  • You cannot specify Cookie or Host.
Values Array of String No 5006

The value of the header.

  • It must be 1 to 128 characters in length.
  • It can contain printable characters whose ASCII values are greater than or equal to 32 and smaller than 127, excluding uppercase letters. You can use asterisks (*) and question marks (?) as wildcards.
  • The header value cannot start or end with a space character.
Type String Yes Host

The type of the 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.
SourceIpConfig Object No

The source IP address based on which user traffic is matched. This parameter is required and takes effect only when Type is set to SourceIP.

Values Array of String No 192.168.0.0/32

The IP addresses or CIDR blocks.

You can specify at most five values for SourceIp.

RuleName String Yes rule-a3x3pg1yohq3lq****

The name of the forwarding rule.

  • It must be 2 to 128 characters in length.
  • It can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter.
Direction String No Request

The direction to which the forwarding rule is applied. Valid values:

  • Request (default): The forwarding rule is applied to the client requests received by ALB.
  • Response: The forwarding rule is applied to the responses returned by backend servers.
Note You cannot set the value to Response if you use a basic ALB instance.

Response parameters

Parameter Type Example Description
JobId String 72dcd26b-f12d-4c27-b3af-18f6aed5****

The ID of the asynchronous task.

RequestId String 365F4154-92F6-4AE4-92F8-7FF34B540710

The ID of the request.

RuleIds Array of RuleId

The list of forwarding rules.

RuleId String rule-a3x3pg1yohq3lq****

The ID of the forwarding rule.

Priority Integer 10

The priority of the forwarding rule. Valid values: 1 to 10000. A lower value specifies a higher priority.

Note The priority of each forwarding rule within a listener is unique.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateRules
&ListenerId=lsr-bp1bpn0kn908w4nbw****
&ClientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF3898
&DryRun=true
&Rules=[{"Priority":10,"RuleActions":[{"FixedResponseConfig":{"Content":"dssacav","ContentType":"text/plain","HttpCode":"HTTP_200"},"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"sgp-k86c1ov501id6p****","Weight":100}],"ServerGroupStickySession":{"Enabled":false,"Timeout":2}},"InsertHeaderConfig":{"Key":"key","Value":"UserDefined","ValueType":"UserDefined"},"Order":1,"RedirectConfig":{"Host":"www.example.com","HttpCode":"301","Path":"/test","Port":"10","Protocol":"HTTP","Query":"quert"},"RewriteConfig":{"Host":"www.example.com","Path":"/tsdf","Query":"quedsa"},"Type":"ForwardGroup","TrafficLimitConfig":{"QPS":100},"TrafficMirrorConfig":{"TargetType":"ForwardGroupMirror","MirrorGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"srg-00mkgijak0w4qgz9****"}]}}}],"RuleConditions":[{"CookieConfig":{"Values":[{"Key":"test","Value":"test"}]},"HeaderConfig":{"Key":"Port","Values":["5006"]},"HostConfig":{"Values":["www.example.com"]},"MethodConfig":{"Values":["PUT"]},"PathConfig":{"Values":["/test"]},"QueryStringConfig":{"Values":[{"Key":"test","Value":"test"}]},"ResponseHeaderConfig":{"Key":"Port","Values":["5006"]},"Type":"Host","SourceIpConfig":{"Values":["192.168.0.0/32"]}}],"RuleName":"rule-a3x3pg1yohq3lq****","Direction":"Request"}]
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateRulesResponse>
    <JobId>72dcd26b-f12d-4c27-b3af-18f6aed5****</JobId>
    <RequestId>365F4154-92F6-4AE4-92F8-7FF34B540710</RequestId>
    <RuleIds>
        <RuleId>rule-a3x3pg1yohq3lq****</RuleId>
        <Priority>10</Priority>
    </RuleIds>
</CreateRulesResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

HttpCode Error code Error message Description
400 IncorrectStatus.Listener The status of %s [%s] is incorrect. The error message returned because the status of the specified resource %s [%s] is invalid.
400 OperationDenied.IpGroupCanNotUsedForMirrorAction The operation is not allowed because of %s. The error message returned because the operation is not allowed due to %s.
400 OperationDenied.SameGroupForForwardAndMirrorAction The operation is not allowed because of %s. The error message returned because the operation is not allowed due to %s.
400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s. The error message returned because the operation is not allowed due to %s.
400 Conflict.Priority There is already %s having the same configuration with %s. The error message returned because an existing %s has the same configuration.
400 ResourceQuotaExceeded.LoadBalancerRulesNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the quota %s of the specified resource %s is exhausted. The current usage is %s.
400 QuotaExceeded.RuleWildcardsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has exceeded the quota %s.
400 QuotaExceeded.RuleMatchEvaluationsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has exceeded the quota %s.
400 QuotaExceeded.RuleActionsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has exceeded the quota %s.
400 Mismatch.VpcId The %s is mismatched for %s and %s. The error message returned because %s does not correspond to %s and %s.
400 Mismatch.Protocol The %s is mismatched for %s and %s. The error message returned because %s does not correspond to %s and %s.
400 OperationDenied.RewriteMissingForwardGroup The operation is not allowed because of RewriteMissingForwardGroup. The error message returned because no destination server group is configured for the rewrite action.
404 ResourceNotFound.Listener The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.ServerGroup The specified resource %s is not found. The error message returned because the specified resource %s does not exist.

For a list of error codes, visit the API Error Center.