Creates multiple 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 configured for 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.

DryRun Boolean No true

Specifies whether only to precheck the request. Valid values:

true: only prechecks the request and does not perform the requested operation. The system checks the required parameters, request format, and service limits. If the request fails the precheck, an error code is returned based on the cause of the failure. If the request passes the precheck, the DryRunOperation error code is returned.

false: prechecks the request and performs the requested operation. After the request passes the precheck, an HTTP 2xx status code is returned and the system performs the operation. This is the default value.

Rules Array Yes

The forwarding rules.

Priority Integer Yes 10

The priority of the forwarding rule. Valid values: 1 to 10000. A smaller value indicates 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 fixed response.

Content String No dssacav

The content of the fixed response. The content can be up to 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, and application/json.

HttpCode String No 200

The HTTP status code of the response. Valid values: HTTP_2xx, HTTP_4xx, and HTTP_5xx. x is a digit.

ForwardGroupConfig Object No

The configuration of 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 headers added to a request.

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 (-). Each header name specified in the InsertHeaderConfig parameter must be unique.

Note Do not use the following header names:

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

Value String No ClientSrcPort

The value of the header.

If the ValueType parameter is set to SystemDefined, valid values are:

  • ClientSrcPort: the port of the client.
  • ClientSrcIp: the IP address of the client.
  • Protocol: the request protocol of the client, such as HTTP or HTTPS.
  • SLBId: the ID of the ALB instance.
  • SLBPort: the listener port of the ALB instance.

If the ValueType parameter is set to UserDefined, you can define a value for the header. The value must be 1 to 128 characters in length. The value can contain lowercase letters, printable characters whose ASCII value is greater than or equal to 32 and smaller than 127, and wildcards such as asterisks (*) and question marks (?). The value cannot start or end with a space.

If the ValueType parameter is set to ReferenceHeader, you can reference the value of a request header. The 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 value. Valid values:

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

The priority of the forwarding action. Valid values: 1 to 50000. A smaller value indicates 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 external redirect action.

Host String No ww.ali.com

The hostname of the destination to which requests are forwarded.

Rules for valid values:

  • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.),and wildcards such as asterisks (*) and question marks (?).
  • The hostname 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 include wildcards such as asterisks (*) and question marks (?)anywhere in a field.

Default value: ${host}. You cannot use this variable together with other characters.

HttpCode String No 301

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

Path String No /test

The path of the destination to which requests are forwarded.

Rules for valid values: 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 path is case-sensitive, and can contain wildcards such as asterisks (*) and question marks (?).

Default value: ${path}. ${host}, ${protocol}, and ${port} are also supported. You can use each variable only once. You can use the preceding variables at the same time, or use them together with a valid string.

Port String No 10

The port to which requests are forwarded.

Valid values: 1 to 63335.

Default value: ${port}. You cannot use this variable together with other characters.

Protocol String No HTTP

The protocol of the destination to which requests are forwarded.

Valid values: HTTP and HTTPS.

Default value: ${protocol}. You cannot use this variable together with other characters.

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

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

Rules for valid values: The query string must be 1 to 128 characters in length. It can contain lowercase letters and other printable characters. It cannot contain the following special characters:

# [ ] { } \ | < > &.

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

RewriteConfig Object No

The configuration of the internal rewrite action.

Host String No www.al.com

The hostname of the destination to which requests are forwarded.

Rules for valid values:

  • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.),and wildcards such as asterisks (*) and question marks (?).
  • The hostname 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 include wildcards such as asterisks (*) and question marks (?)anywhere in a field.

Default value: ${host}. You cannot use this variable together with other characters.

Path String No /tsdf

The path of the destination to which requests are forwarded.

Rules for valid values: 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 path is case-sensitive, and can contain wildcards such as asterisks (*) and question marks (?).

Default value: ${path}. You can use this variable only once. You can use this variable together with a valid string.

Query String No quedsa

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

Rules for valid values: The query string must be 1 to 128 characters in length. It can contain lowercase letters and other printable characters. It cannot contain the following special characters:

# [ ] { } \ | < > &.

Default value: ${query}. You can use this variable only once. You can use this variable together with a valid string.

Type String Yes ForwardGroup

The type of the forwarding action. Valid values:

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

Valid types:

FinalType: the last action to be performed in a forwarding rule. Each forwarding rule can contain only one FinalType action. Valid values: ForwardGroup, Redirect, and FixedResponse.

ExtType: the action or the actions to be performed before the FinalType action. A forwarding rule can contain one or more ExtType actions. To specify this type of action, you must also specify the FinalType action. You can specify multiple InsertHeader actions or one Rewrite action.

RuleConditions Array Yes

The conditions of the forwarding rule.

CookieConfig Object No

The configuration of cookies.

Values Array No

The values of the cookies.

Key String No test

The key of the cookie. The key must be 1 to 100 characters in length, and can contain lowercase letters, printable characters, and wildcards such as asterisks (*) and question marks (?). The key cannot contain spaces or the following special characters:

# [ ] { } \ | < > &.

Value String No test

The value of the cookie. The value must be 1 to 128 characters in length, and can contain lowercase letters, printable characters, and wildcards such as asterisks (*) and question marks (?). The value cannot contain spaces or the following special characters:

# [ ] { } \ | < > &.

HeaderConfig Object No

The configuration of headers.

Key String No Port

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

Values Array of String No 5006

The values of the header. The value must be 1 to 128 characters in length, and can contain lowercase letters, printable characters whose ASCII value is greater than or equal to 32 and smaller than 127, and wildcards such as asterisks (*) and question marks (?). The value cannot start or end with a space.

HostConfig Object No

The configuration of hostnames.

Values Array of String No www.test.com

The hostnames.

Rules for valid values:

  • The hostname must be 3 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), periods (.),and wildcards such as asterisks (*) and question marks (?).
  • The hostname 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 include wildcards such as asterisks (*) and question marks (?)anywhere in a field.
MethodConfig Object No

The configuration of 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 configuration of paths.

Values Array of String No /test

The paths.

Rules for valid values: 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 path is case-sensitive, and can contain wildcards such as asterisks (*) and question marks (?).

QueryStringConfig Object No

The configuration of query strings.

Values Array No

The query strings.

Key String No test

The key of the query string.

The key must be 1 to 100 characters in length, and can contain lowercase letters, printable characters, and wildcards such as 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, and wildcards such as asterisks (*) and question marks (?). The value cannot contain spaces or the following special characters:

# [ ] { } \ | < > &.

ResponseHeaderConfig Object No

The configuration of response headers.

Key String No Port

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

Values Array of String No 5006

The values of the header. The value must be 1 to 128 characters in length, and can contain lowercase letters, printable characters whose ASCII value is greater than or equal to 32 and smaller than 127, and wildcards such as asterisks (*) and question marks (?). The value cannot start or end with a space.

Type String Yes Host

The type of the forwarding rule. Valid values:

  • Host: Requests are forwarded based on the hostname.
  • Path: Requests are forwarded based on the path.
  • Header: Requests are forwarded based on the HTTP header.
  • QueryString: Requests are forwarded based on the query string.
  • Method: Requests 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 asynchronous task.

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

The ID of the request.

RuleIds Array of RuleId

The forwarding rules.

RuleId String rule-doc****

The ID of the forwarding rule.

Priority Integer 10

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

Note The priority of each forwarding rule within a listener must be 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":"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"}]},"ResponseHeaderConfig":{"Key":"Port","Values":["5006"]},"Type":"Host"}],"RuleName":"rule-doc****"}]
&<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-doc****</RuleId>
    </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-doc****"
  } ]
}

Error codes

HTTP status code 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 %s [%s] resource 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 usage %s of the specified %s resource has exceeded the quota %s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s of the specified %s resource has exceeded the quota %s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s of the specified %s resource has exceeded the quota %s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s of the specified %s resource has exceeded the quota %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 the specified %s does not correspond to the specified %s and %s.
400 Mismatch.Protocol The %s is mismatched for %s and %s. The error message returned because the specified %s does not correspond to the specified %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 %s resource does not exist.
404 ResourceNotFound.ServerGroup The specified resource %s is not found. The error message returned because the specified %s resource does not exist.

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