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 make sure that it is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

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 only to precheck the request. Valid values:

  • true: prechecks the request without creating the resource. The system checks 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 be greater than 1 KB in size and can contain only ASCII characters.

ContentType String No text/plain

The format of the content. 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 is a digit.

ForwardGroupConfig Object No

The configuration of the server group.

ServerGroupTuples Array No

The list of server groups to which requests are distributed.

ServerGroupId String No sgp-k86c1ov501id6p****

The server group to which requests are distributed.

ServerGroupStickySession Object No

The configuration of session persistence.

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 name of the header. The name must be 1 to 40 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The header name specified by InsertHeaderConfig must be unique.

Note You cannot set the name of the header to one of the following values (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 the Value parameter to one of the following values:
    • ClientSrcPort: the client port.
    • ClientSrcIp: the client IP address.
    • Protocol: the request protocol. You can set the protocol to 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. The header value must be 1 to 128 characters in length, and can contain printable characters from ASCII code 32 to 127 (ch >= 32 && ch < 127). You can use asterisks (*) and question marks (?) as wildcard characters. 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: a header carried in the request
  • 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 action with a higher priority is first performed. This parameter is required. The priority of each action within a forwarding rule is unique.

RedirectConfig Object No

The redirect configuration.

Host String No www.example.com

The hostname to which requests are distributed. Valid values:

  • ${host} (default): If you set the value to ${host}, do not 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 a wildcard.
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 distributed. 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 the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • The value 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 distributed.

  • ${port} (default): If you set the value to ${port}, you cannot append other characters.
  • You can also enter a port number. Valid values: 1 to 63335.
Protocol String No HTTP

The redirect protocol.

  • ${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 distributed.

  • Default value: ${query}. ${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 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 rewrite configuration.

Host String No www.example.com

The host to which requests are distributed. 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 a wildcard.
Path String No /tsdf

The path to which requests are distributed. 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 the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • The value 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 distributed.

  • Default value: ${query}. ${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 the following characters.
  • If you want to specify a custom value, make sure that the following requirements are met:
    • The value 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: distributes 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 configuration of traffic throttling.

QPS Integer No 100

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

TrafficMirrorConfig Object No

The configuration of traffic mirroring.

TargetType String No ForwardGroupMirror

The destination to which network traffic is mirrored.

MirrorGroupConfig Object No

The server group to which network traffic is mirrored.

ServerGroupTuples Array No

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

ServerGroupId String No srg-00mkgijak0w4qgz9****

The ID of the server group.

RuleConditions Array Yes

The conditions in the forwarding rule.

CookieConfig Object No

The configuration of the cookie.

Values Array No

The value of the cookie.

Key String No test

The key of the cookie.

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

The value of the cookie.

  • The value must be 1 to 100 characters in length.
  • You can use asterisks (*) and question marks (?) as wildcards.
  • The value 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 asterisks (*), question marks (?), and other printable characters from ASCII code 32 to 127 (ch >= 32 && ch < 127).
  • The header value cannot start or end with a space character.
HostConfig Object No

The configuration of the host.

Values Array of String No www.example.com

The hostname. 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 a wildcard.
MethodConfig Object No

The configuration of the request method.

Values Array of String No PUT

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

PathConfig Object No

The configuration of the URL.

Values Array of String No /test

The path. Valid values:

  • The path 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

The 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 lowercase letters and other printable characters from ASCII code 32 to 127 (ch >= 32 && ch < 127). You can use asterisks (*) and question marks (?) as wildcards.
  • It 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 configuration of the source IP-based forwarding rule. This parameter is required and takes effect only when Type is set to SourceIP.

Values Array of String No 192.168.XX.XX/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.

  • The name 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 indicates 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":"200"},"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"sgp-cige6j****"}],"ServerGroupStickySession":{"Enabled":true,"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.edu"]},"MethodConfig":{"Values":["PUT"]},"PathConfig":{"Values":["/test"]},"QueryStringConfig":{"Values":[{"Key":"test","Value":"test"}]},"ResponseHeaderConfig":{"Key":"Port","Values":["5006"]},"Type":"Host","SourceIpConfig":{"Values":["192.168.XX.XX/32"]}}],"RuleName":"rule-doc****","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 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.