Creates 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 CreateRule

The operation that you want to perform.

Set the value to CreateRule.

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 false

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 the check, an error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false: sends the API request. This is the default value. If the request passes the precheck, a HTTP_2xx status code is returned and the operation is performed.
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 content type.

Valid values: text/plain, text/css, text/html, application/javascript, and 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 configurations of the server groups.

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 80

The weight of the server group. Valid values: 0 to 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. Default value: 1000.

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 ClientSrcPort

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 ClientSrcPort

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 ${host}

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.

  • ${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 redirection.
Query String No ${query}

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 ${query}

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 type of 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 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 of the forwarding rule.

CookieConfig Object No

The configurations of the cookies.

Values Array No

The list of cookie values.

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.
  • The key can contain printable characters, excluding uppercase letters, space characters, and the 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.edu

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:

  • 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 configurations of the query strings.

Values Array No

The list of query strings.

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. It 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.
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.XX.XX/32

The IP addresses or CIDR blocks.

You can specify at most five values for SourceIp.

RuleName String Yes rule-doc

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.

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-7FF34B540750

The ID of the request.

RuleId String rule-a3x3pg1yohq3lq****

The ID of the forwarding rule.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateRule
&ListenerId=lsr-bp1bpn0kn908w4nbw****
&ClientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF3898
&DryRun=false
&Priority=10
&RuleActions=[{"FixedResponseConfig":{"Content":"dssacav","ContentType":"text/plain","HttpCode":"HTTP_200"},"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"sgp-k86c1ov501id6p****","Weight":80}],"ServerGroupStickySession":{"Enabled":false,"Timeout":2}},"InsertHeaderConfig":{"Key":"key","Value":"ClientSrcPort","ValueType":"ClientSrcPort"},"Order":1,"RedirectConfig":{"Host":"${host}","HttpCode":"301","Path":"/test","Port":"10","Protocol":"HTTP","Query":"${query}"},"RewriteConfig":{"Host":"www.example.com","Path":"/tsdf","Query":"${query}"},"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"}]},"Type":"Host","SourceIpConfig":{"Values":["192.168.XX.XX/32"]}}]
&RuleName=rule-doc
&Common request parameters

Sample success responses

XML format

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

<CreateRuleResponse>
    <JobId>72dcd26b-f12d-4c27-b3af-18f6aed5****</JobId>
    <RequestId>365F4154-92F6-4AE4-92F8-7FF34B540750</RequestId>
    <RuleId>rule-a3x3pg1yohq3lq****</RuleId>
</CreateRuleResponse>

JSON format

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

{
  "JobId" : "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId" : "365F4154-92F6-4AE4-92F8-7FF34B540750",
  "RuleId" : "rule-a3x3pg1yohq3lq****"
}

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.SameGroupForForwardAndMirrorAction The operation is not allowed because of %s. The error message returned because the operation is not allowed due to %s.
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.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.Protocol The %s is mismatched for %s and %s. The error message returned because %s does not correspond to %s and %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 OperationDenied.RewriteMissingForwardGroup The operation is not allowed because of RewriteMissingForwardGroup. The error message returned because no server group is configured for the rewrite action.
400 ResourceInConfiguring.Listener The specified listener is being configured, please try again later. The error message returned because the resource is being modified. Try again later.
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.