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 Application Load Balancer (ALB) listener.

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

The client token that is used to ensure the idempotency of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

DryRun Boolean No false

Specifies whether to precheck this request. Valid values:

  • true: prechecks the API request. Resources are not created. The system checks the required parameters, request format, and service limits. If the request fails the check, the corresponding error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false (default): checks the request. After the request passes the check, an HTTP_2xx status code is returned and the operation is performed.
Priority Integer Yes 10

The priority of the rule. Valid values: 1 to 10000. A smaller value indicates a higher priority.

Note The priority value of each rule within the same listener must be unique.
RuleActions Array Yes

The actions of the forwarding rule.

FixedResponseConfig Object No

The configuration of the fixed response.

Content String No dssacav

The fixed response. The response cannot exceed 1 KB in size and can contain only ASCII characters.

ContentType String No text/plain

The format of the fixed response.

Valid values: text/plain, text/css, text/html, application/javascript, and application/json.

HttpCode String No 200

The HTTP status code of the response. The code must be an HTTP_2xx,HTTP_4xx or HTTP_5xx.x is a digit.

ForwardGroupConfig Object No

The configurations of the destination server groups.

ServerGroupTuples Array No

The destination server groups to which requests are forwarded.

ServerGroupId String No sg-xxxxx

The ID of the destination server group.

InsertHeaderConfig Object No

The configuration of the header field.

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 (-). You cannot set InsertHeader to the same name.

Note You cannot set this parameter to the following values:

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. These values are not case-sensitive.

Value String No ClientSrcPort

The content of the header.

Valid values:

  • ClientSrcPort: the port of the client
  • ClientSrcIp: the IP address of the client
  • Protocol: the protocol used by client requests (HTTP or HTTPS)
  • SLBId: the ID of the ALB instance
  • SLBPort: the listener port of the ALB instance

UserDefined: Enter a custom value. The value must be 1 to 128 characters in length, and can contain asterisks (*), question marks (?), and printable ASCII characters whose values are ch >= 32 && ch < 127. The value can contain only lowercase letters, and cannot start or end with spaces.

ReferenceHeader: The value uses the reference type. The value must be 1 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), and underscores (_).

ValueType String No ClientSrcPort

Valid values:

  • UserDefined: a user-defined value
  • ReferenceHeader: uses a field of the user request header.
  • SystemDefined: a system-defined value
Order Integer Yes 1

The order of the forwarding rule actions. Valid values:1 to 50000. The actions are performed in ascending order. You cannot leave this parameter empty. Each value must be unique.

RedirectConfig Object No

The configuration of the external redirect action.

Host String No ww.ali.com

The host name of the destination to which requests are redirected.

The host must meet the following rules:

  • The host name must be 3 to128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (*), and question marks (?).
  • The host name must contain at least one period (.), and cannot start or end with a period (.).
  • The rightmost field can contain only letters and wildcards, and cannot contain digits or hyphens (-).
  • Other fields cannot start or end with a hyphen (-). You can enter asterisks (*) and question marks (?) anywhere in a field.

Default value: ${host}. You cannot use this value with other characters at the same time.

HttpCode String No 301

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

Path String No /test

The path of the destination to which requests are redirected.

The path must be 1 to 128 characters in length and must start with a forward slash (/). The path can contain letters, digits, and the following special characters: $ - _ .+ / & ~ @ :. It cannot contain the following special characters: " % # ; ! ( ) [ ] ^ , ". The value is case-sensitive and can contain asterisks (*) and question marks (?).

Default value: ${path}. You can also reference ${host}, ${protocol}, and ${port}. Each variable can appear at most once. You can use the preceding variables at the same time, or use them with a valid string.

Port String No 10

The port of the destination to which requests are redirected.

Valid values: 1 to 63335.

Default value: ${port}. You cannot use this value with other characters at the same time.

Protocol String No HTTP

The protocol of the requests to be redirected.

Valid values: HTTP and HTTPS.

Default value: ${protocol}. You cannot use this value with other characters at the same time.

Note HTTPS listeners can redirect only HTTPS requests.
Query String No quert

The query string of the request to be redirected.

The value must be 1 to 128 characters in length, and can contain letters and printable characters. It cannot contain the following special characters: # [ ] { } \ | < > &.

Default value: ${query}. You can also reference ${host}, ${protocol}, and ${port}. Each variable can appear at most once. You can use the preceding variables at the same time, or use them together with a valid string.

RewriteConfig Object No

The redirect action within ALB.

Host String No www.al.com

The host name of the destination to which requests are redirected within ALB.

The host name must meet the following rules:

  • The host name must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.),asterisks (*), and question marks (?).
  • The host name must contain at least one period (.), andcannot start or end with a period (.).
  • The rightmost field can contain only letters and wildcards, and cannot contain digits or hyphens (-).
  • Other fields cannot start or end with a hyphen (-). You can enter asterisks (*) and question marks (?) anywhere in a field.

Default value: ${host}. You cannot use this value together with other characters at the same time.

Path String No /tsdf

The path to which requests are to be redirected within ALB.

The value must be 1 to 128 characters in length and must start with a forward slash (/). The value can contain letters, digits, and the following special characters: $ - _ .+ / & ~ @ :. It cannot contain the following special characters: " % # ; ! ( ) [ ]^ , ". The value is case-sensitive and can contain asterisks (*) and question marks (?).

Default value: ${path}. This value can be used only once. You can use it with a valid string.

Query String No quedsa

The query string of the request to be redirected within ALB.

The query string must be 1 to 128 characters in length, can contain letters and printable characters. It cannot contain the following special characters: # [ ] { } \ | < > &.

Default value: ${query}. This value can be used only once. You can use it with a valid string.

Type String Yes ForwardGroup

The action. Valid values:

  • ForwardGroup: forwards requests to multiple vServer groups.
  • Redirect: redirects requests.
  • FixedResponse: returns a fixed response.
  • Rewrite: rewrites requests.
  • InsertHeader: inserts header fields to requests.

Type:

  • FinalType: A forwarding rule can contain only one FinalType action, which is executed last. This type of action can contain only one ForwardGroup, Redirect or FixedResponse action.
  • ExtType: A forwarding rule can contain one or more ExtType actions, which are executed before FinalType actions and need to coexist with the FinalType actions. This type of action can contain multiple InsertHeader actions or one Rewrite action.
RuleConditions Array Yes

The conditions of the forwarding rule.

CookieConfig Object No

The configuration of the cookie.

Values Array No

The configuration of the cookie.

Key String No test

The key of the cookie. It must be 1 to 100 characters in length, and can contain lowercase letters, printable characters, asterisks (*), and question marks (?). It cannot contain spaces or the following special characters: # [ ] { } \ | < > &.

Value String No test

The value of the cookie. It must be 1 to 128 characters in length, and can contain lowercase letters, printable characters, asterisks (*), and question marks (?). It cannot contain spaces or the following special characters: # [ ] { } \ | < > &.

HeaderConfig Object No

The configuration of the header field.

Key String No Port

The key of the header field. The key must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-) and underscores (_). The key does not support Cookie or Host.

Values Array of String No 5006

The value of the header field. The value must be 1 to 128 characters in length, and can contain lowercase letters, printable ASCII characters whose values are ch >= 32 && ch < 127, asterisks (*), and question marks (?). The value cannot start or end with a space.

HostConfig Object No

The configuration of the host.

Values Array of String No www.test.com

The name of the host.

The host name must meet the following rules:

  • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.), asterisks (*), and question marks (?).
  • The host name must contain at least one period (.), and cannot start or end with a period (.).
  • The rightmost field can contain only letters and wildcards, and cannot contain digits or hyphens (-).
  • Other fields cannot start or end with a hyphen (-). You can enter asterisks (*) and question marks (?) anywhere in a field.
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 path for the request to be forwarded.

Values Array of String No /test

The path of the request to be forwarded.

The path must be 1 to 128 characters in length and must start with a forward slash (/). The path can contain letters, digits, and the following special characters: $ - _ . + / & ~ @ :. It cannot contain the following special characters: " % # ; ! ( ) [ ] ^ , ". The value is case-sensitive, and can contain asterisks (*) and question marks (?).

QueryStringConfig Object No

The configuration of the query string.

Values Array No

The query string.

Key String No test

They key of the query string.

The key must be 1 to 100 characters in length, and can contain lowercase letters, printable characters, asterisks (*), and question marks (?). The key cannot contain spaces or the following special characters: # [ ] { } \ | < > &.

Value String No test

The value of the query string.

The value must be 1 to 128 characters in length, and can contain lowercase letters, printable characters, asterisks (*), and question marks (?). The value cannot contain spaces or the following special characters: # [ ] { } \ | < > &.

Type String Yes Host

The type of the forwarding rule. Valid values:

  • Host: Requests are forwarded based on the host.
  • Path: Requests are forwarded based on the path.
  • Header: Requests are forwarded based on the HTTP header field.
  • QueryString: Requests are forwarded based on the query string.
  • Method: Request are forwarded based on the request method.
  • Cookie: Requests are forwarded based on the cookie.
RuleName String Yes rule-doc****

The name of the forwarding rule. The name must be 2 to 128 characters in length, and can contain letters, digits, periods (.), underscores (_), and hyphens (-). The name must start with a letter.

Response parameters

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

The ID of the query task.

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

The ID of the request.

RuleId String rule-doc****

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":"200"},"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"sg-xxxxx"}]},"InsertHeaderConfig":{"Key":"key","Value":"ClientSrcPort","ValueType":"ClientSrcPort"},"Order":1,"RedirectConfig":{"Host":"ww.ali.com","HttpCode":"301","Path":"/test","Port":"10","Protocol":"HTTP","Query":"quert"},"RewriteConfig":{"Host":"www.al.com","Path":"/tsdf","Query":"quedsa"},"Type":"ForwardGroup"}]
&RuleConditions=[{"CookieConfig":{"Values":[{"Key":"test","Value":"test"}]},"HeaderConfig":{"Key":"Port","Values":["5006"]},"HostConfig":{"Values":["www.test.com"]},"MethodConfig":{"Values":["PUT"]},"PathConfig":{"Values":["/test"]},"QueryStringConfig":{"Values":[{"Key":"test","Value":"test"}]},"Type":"Host"}]
&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-7FF34B540710</RequestId>
    <RuleId>rule-doc****</RuleId>
</CreateRuleResponse>

JSON format

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

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

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 %s exists that has the same configuration with %s.
400 ResourceQuotaExceeded.LoadBalancerRulesNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 QuotaExceeded.RuleWildcardsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s.
400 QuotaExceeded.RuleMatchEvaluationsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s.
400 QuotaExceeded.RuleActionsNum The quota of %s is exceeded, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s.
400 Mismatch.Protocol The %s is mismatched for %s and %s. The error message returned because %s does not match %s in %s.
400 Mismatch.VpcId The %s is mismatched for %s and %s. The error message returned because %s does not match %s in %s.
400 OperationDenied.RewriteMissingForwardGroup The operation is not allowed because of RewriteMissingForwardGroup. The error message returned because the rewrite is not configured for the destination group.
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.