All Products
Search
Document Center

Server Load Balancer:UpdateRuleAttribute

最終更新日:Sep 10, 2024

Updates a forwarding rule, such as the match condition, action, and name.

Operation description

  • UpdateRuleAttribute is an asynchronous operation. After a request is sent, the system returns a request ID and runs the task in the background. You can call the ListRules operation to query the status of a forwarding rule:

    • If a forwarding rule is in the Configuring state, the forwarding rule is being updated.
    • If a forwarding rule is in the Available state, the forwarding rule is updated.
  • You can set RuleConditions and RuleActions to add conditions and actions to a forwarding rule. Take note of the following limits on the number of conditions and the number of actions in each forwarding rule:

    • Number of conditions: You can specify at most 5 for a basic Application Load Balancer (ALB) instance, at most 10 for a standard ALB instance, and at most 10 for a WAF-enabled ALB instance.
    • Number of actions: You can specify at most 3 for a basic ALB instance, at most 5 for a standard ALB instance, and at most 5 for a WAF-enabled ALB instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

ParameterTypeRequiredDescriptionExample
RuleIdstringYes

The ID of the forwarding rule.

rule-4dp5i6ea****
ClientTokenstringNo

The client token that is used to ensure the idempotence of the request.

You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters.

Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.
5A2CFF0E-5718-45B5-9D4D-70B3FF3898
DryRunbooleanNo

Specifies whether to perform only a dry run, without performing the actual request. Valid values:

  • true: performs a dry run. The system checks the request for potential issues, including missing parameter values, incorrect request syntax, and service limits. If the request fails the dry run, an error code is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false (default): performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
false
RuleConditionsarray<object>No

The match conditions of the forwarding rule.

objectNo

The match condition of the forwarding rule.

CookieConfigobjectNo

The key-value pairs of the cookie.

Valuesarray<object>No

The key-value pairs of the cookie.

objectNo

The key-value pairs of the cookie.

KeystringNo

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

test
ValuestringNo

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

test
HeaderConfigobjectNo

The configuration of the header.

KeystringNo

The header key. The header key must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). Cookie and Host are not supported.

Port
ValuesarrayNo

The header values.

stringNo

The header values. The header values within a forwarding rule must be unique. The header value must meet the following requirements:

  • The header value must be 1 to 128 characters in length.
  • It can contain asterisks (*), question marks (?), and other printable characters whose ASCII values are larger than or equal to 32 and smaller than 127.
  • The value cannot start or end with a space character.
5006
HostConfigobjectNo

The configurations of the hosts.

ValuesarrayNo

The hostnames.

stringNo

The hostname. The hostname must meet the following requirements:

  • 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, asterisks (*), and question marks (?), and cannot contain digits or hyphens (-).
  • The domain labels cannot start or end with hyphens (-). You can specify asterisks (∗) and question marks (?) anywhere in a domain label.
www.example.com
MethodConfigobjectNo

The configuration of the request method.

ValuesarrayNo

The request methods.

stringNo

The request method.

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

PUT
PathConfigobjectNo

The configurations of the forwarding URL.

ValuesarrayNo

The forwarding URLs.

stringNo

The URL to which requests are forwarded. The URL must meet the following requirements:

  • The URL must be 1 to 128 characters in length,
  • The URL 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 wildcard characters.
/test
QueryStringConfigobjectNo

The configurations of the query strings.

Valuesarray<object>No

The query strings. You can specify at most 20 query strings.

objectNo

The query string.

KeystringNo

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

test
ValuestringNo

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

test
TypestringNo

The type of forwarding rule. You can specify at most seven types of forwarding rule. Valid values:

  • Host: Requests are forwarded based on hosts.
  • Path: Requests are forwarded based on paths.
  • Header: Requests are forwarded based on HTTP headers.
  • QueryString: Requests are forwarded based on query strings.
  • Method: Requests are forwarded based on request methods.
  • Cookie: Requests are forwarded based on cookies.
  • SourceIp: Requests are forwarded based on source IP addresses.
  • ResponseHeader: Requests are forwarded based on HTTP response headers.
  • ResponseStatusCode: Requests are forwarded based on response status codes.
Host
ResponseStatusCodeConfigobjectNo

The configurations of the response status codes.

ValuesarrayNo

The response status codes.

stringNo

The response status code.

test
ResponseHeaderConfigobjectNo

The configuration of headers.

KeystringNo

The key of the response header.

  • The key must be 1 to 40 characters in length.
  • It can contain letters, digits, hyphens (-), and underscores (_).
  • Cookie and Host are not supported.
test
ValuesarrayNo

The values of the header.

stringNo

The values of the header.

  • The header value must be 1 to 128 characters in length.
  • It can contain printable characters whose ASCII values are larger than or equal to 32 and smaller than 127, lowercase letters, asterisks (*), and question marks (?).
  • The value cannot start or end with a space character.
50006
SourceIpConfigobjectNo

Traffic matching based on source IP addresses. You can specify at most five IP addresses, including CIDR blocks.

ValuesarrayNo

You can add one or more IP addresses, including CIDR blocks.

stringNo

You can add one or more IP addresses, including CIDR blocks.

192.168.0.0/32
RuleActionsarray<object>No

The actions of the forwarding rule.

objectNo

The actions of the forwarding rule.

FixedResponseConfigobjectNo

The configuration of the custom response.

ContentstringNo

The content of the response. The content can be up to 1 KB in size, and can contain only ASCII characters.

dssacav
ContentTypestringNo

The content type.

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

text/plain
HttpCodestringNo

The HTTP status code in responses. Valid values: 2xx, 4xx, 5xx. The value must be a numeric string. x must be a digit.

HTTP_200
ForwardGroupConfigobjectNo

The configurations of the server groups.

ServerGroupTuplesarray<object>No

The server groups to which requests are forwarded.

objectNo

The server group to which requests are forwarded.

ServerGroupIdstringNo

The ID of the server group to which requests are forwarded.

sg--atstuj3rtoptyui****
WeightintegerNo

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.

  • If the number of destination server groups is 1, the default weight of the server group is 100, unless you specify a weight.
  • If the number of destination server groups is larger than 1, you must specify a weight.
30
ServerGroupStickySessionobjectNo

The configuration of session persistence.

EnabledbooleanNo

Specify whether to enable session persistence. Valid values:

  • true
  • false (default)
false
TimeoutintegerNo

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

2
InsertHeaderConfigobjectNo

The configuration of the header to be inserted.

CoverEnabledbooleanNo

Specifies whether to overwrite the request header values. Valid values:

  • true
  • false
false
KeystringNo

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

Note The following header keys are not supported: 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. The header keys are not case-sensitive.
key
ValuestringNo

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 IP address of the client.
    • Protocol: the request protocol (HTTP or HTTPS).
    • SLBId: the ID of the ALB instance.
    • SLBPort: the listener port.
  • If ValueType is set to UserDefined, you can specify a custom value. The value must be 1 to 128 characters in length, and can contain asterisks (*), question marks (?), and printable characters whose ASCII values are larger than or equal to 32 and smaller than 127. It cannot start or end with a space character.

  • If ValueType is set to ReferenceHeader, you can reference a value from request headers. The value must be 1 to 128 characters in length, and can contain lowercase letters, digits, hyphens (-), and underscores (_).

UserDefined
ValueTypestringNo

The type of the header. Valid values:

  • UserDefined: a custom header.
  • ReferenceHeader: a header that references one of the request headers.
  • SystemDefined: a system-defined header value.
UserDefined
OrderintegerNo

The priority of the action. Valid values: 1 to 50000. A smaller 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. You can specify at most 20 forwarding rule priorities.

1
RedirectConfigobjectNo

The configuration of the redirect action. You can specify at most 20 redirect actions.

HoststringNo

The hostname to which requests are redirected. Valid values:

  • ${host} (default): If ${host} is returned, no other character is appended.

  • A custom value that meets the following requirements:

    • 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 asterisks (*) and question marks (?) anywhere in a domain label as wildcard characters.
www.example.com
HttpCodestringNo

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

301
PathstringNo

The URL to which requests are redirected. Valid values:

  • Default value: ${path}. **${host}**, ${protocol}, and **${port}** are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value.

  • A custom value that meets the following requirements:

    • The URL 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 does not contain the following special characters: " % # ; ! ( ) [ ] ^ , ". You can use asterisks (*) and question marks (?) as wildcard characters.
/test
PortstringNo

The port to which requests are redirected. Valid values:

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

The redirect protocol. Valid values:

  • ${protocol} (default): If ${protocol} is returned, no other character is appended.
  • HTTP or HTTPS.
Note HTTPS listeners support only HTTPS redirects.
HTTP
QuerystringNo

The query string to which requests are redirected. Valid values:

  • Default value: ${query}. **${host}**, ${protocol}, and **${port}** are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value.

  • A custom value that meets the following requirements:

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

The configuration of the rewrite action.

HoststringNo

The hostname to which requests are rewritten. Valid values:

  • ${host} (default): If you set the value to ${host}, you cannot append other characters.

  • A custom value that meets the following requirements:

    • 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 asterisks (*) and question marks (?) anywhere in a domain label as wildcard characters.
www.example.com
PathstringNo

The URL to which requests are redirected. Valid values:

  • Default value: ${path}. **${host}**, ${protocol}, and **${port}** are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value.

  • A custom value that meets the following requirements:

    • The URL 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.
/tsdf
QuerystringNo

The query string to which requests are redirected. Valid values:

  • Default value: ${query}. **${host}**, ${protocol}, and **${port}** are also supported. Each variable can be specified only once. The preceding variables can be used at the same time or combined with a custom value.

  • A custom value that meets the following requirements:

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

The type of the task. You can specify at most 11 types of action. Valid values:

  • ForwardGroup: forwards requests to multiple vServer groups.
  • Redirect: redirects requests.
  • FixedResponse: returns a custom response.
  • Rewrite: rewrites requests.
  • InsertHeader: inserts headers.
  • RemoveHeader: removes headers.
  • TrafficLimit: throttles traffic.
  • trafficMirror: mirrors network traffic.
  • Cors: forwards requests based on CORS.

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

  • FinalType: Each forwarding rule can contain only one FinalType action, which is performed at the end. You can specify only one of ForwardGroup, Redirect, and FixedResponse.
  • ExtType: Each forwarding rule can contain one or more ExtType actions, which are performed before the FinalType action. If you want to specify an ExtType action, you must also specify a FinalType action. You can specify multiple InsertHeader actions or one Rewrite action.
ForwardGroup
TrafficLimitConfigobjectNo

The configuration of the action to throttle traffic.

QPSintegerNo

The number of queries per second (QPS). Value range: 1 to 1000000.

100
PerIpQpsintegerNo

The number of requests per IP address. Value range: 1 to 1000000.

Note If both the QPS and PerIpQps parameters are specified, make sure that the value of the QPS parameter is smaller than the value of the PerIpQps parameter.
80
TrafficMirrorConfigobjectNo

The configuration of the traffic mirroring action.

TargetTypestringNo

The type of destination to which network traffic is mirrored. Valid values:

  • ForwardGroupMirror: a server group.
ForwardGroupMirror
MirrorGroupConfigobjectNo

The server group to which network traffic is mirrored.

ServerGroupTuplesarray<object>No

The server group to which network traffic is mirrored.

objectNo

The server group to which network traffic is mirrored.

ServerGroupIdstringNo

The server group ID.

srg-00mkgijak0w4qgz9****
RemoveHeaderConfigobjectNo

The HTTP header to be removed.

KeystringNo

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

  • If Direction is set to Request, the following header keys are not supported: 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. The header keys are not case-sensitive.
  • If Direction is set to Response, the following header keys are not supported: connection, upgrade, content-length, and transfer-encoding. The header keys are not case-sensitive.
test
CorsConfigobjectNo

The CORS configuration.

AllowOriginarrayNo

The trusted origins of CORS requests. One or more values are supported. Asterisks (*) can be used as wildcard characters.

  • Each value must start with http:// or https://, which must be followed by a valid domain name, including top-level domain names. Example: http://*.test.abc.example.com.
  • You can specify a port in each value or leave the port empty. Valid values: 1 to 65535.
stringNo

The trusted origin of CORS requests.

http://test.com
AllowMethodsarrayNo

The trusted HTTP methods of CORS requests.

stringNo

The trusted HTTP method of CORS requests. Valid values:

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • OPTIONS
  • PATCH
GET
AllowHeadersarrayNo

The trusted headers of CORS requests.

stringNo

The trusted headers of CORS requests. One or more values are supported. Asterisks (*) can be used as wildcard characters. Multiple values are separated by commas (,). Each value can be up to 32 characters in length, and can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-).

test_123
ExposeHeadersarrayNo

The headers that can be exposed.

stringNo

The header that can be exposed. One or more values are supported. Asterisks (*) can be used as wildcard characters. Multiple values are separated by commas (,). Each value can be up to 32 characters in length, and can contain only letters and digits. It cannot start or end with an underscore (_) or a hyphen (-).

test_123
AllowCredentialsstringNo

Specifies whether to allow credentials to be carried in CORS requests. Valid values:

  • on
  • off
on
MaxAgelongNo

The maximum cache time of dry run requests in the browser. Unit: seconds.

Valid values: -1 to 172800.

1000
RuleNamestringNo

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.

rule-instance-test
PriorityintegerNo

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

Note The priorities of the forwarding rules created for the same listener must be unique.
10

Response parameters

ParameterTypeDescriptionExample
object

Updates a forwarding rule.

JobIdstring

The asynchronous task ID.

72dcd26b-f12d-4c27-b3af-18f6aed5****
RequestIdstring

The request ID.

365F5378-41F6-4AE4-92F8-7FF34B540710

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400IncorrectStatus.RuleThe status of %s [%s] is incorrect.The status of %s [%s] is incorrect.
400OperationDenied.IpGroupCanNotUsedForMirrorActionThe operation is not allowed because of %s.The operation is not allowed because of %s.
400OperationDenied.SameGroupForForwardAndMirrorActionThe operation is not allowed because of %s.The operation is not allowed because of %s.
400OperationDenied.GRPCServerGroupThe operation is not allowed because of %s.The operation is not allowed because of %s.
400Conflict.PriorityThere is already %s having the same configuration with %s.There is already %s having the same configuration with %s.
400ResourceQuotaExceeded.ServerGroupAttachedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s, usage %s/%s.
400ResourceQuotaExceeded.LoadBalancerServersNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
400ResourceQuotaExceeded.ServerAddedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
400QuotaExceeded.RuleWildcardsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded, usage %s/%s.
400QuotaExceeded.RuleMatchEvaluationsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded. Usage: %s/%s.
400QuotaExceeded.RuleActionsNumThe quota of %s is exceeded, usage %s/%s.The quota of %s is exceeded. Usage: %s/%s.
400Mismatch.ProtocolThe %s is mismatched for %s and %s.The %s is mismatched for %s and %s.
400Mismatch.VpcIdThe %s is mismatched for %s and %s.The %s is mismatched for %s and %s.
400OperationDenied.RewriteMissingForwardGroupThe operation is not allowed because of RewriteMissingForwardGroup.The operation is not allowed because rewrite is missing the forward group.
400ResourceInConfiguring.ListenerThe specified listener is being configured, please try again later.-
400OperationDenied.ProtocolMustSameForForwardGroupActionThe operation is not allowed because of ProtocolMustSameForForwardGroupAction.-
403Forbidden.ServerGroupAuthentication has failed for ServerGroup.-
403Forbidden.LoadBalancerAuthentication is failed for %s.Authentication is failed for %s.
404ResourceNotFound.RuleThe specified resource %s is not found.The specified resource %s is not found.
404ResourceNotFound.ServerGroupThe specified resource %s is not found.The specified resource %s is not found.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-01-29The Error code has changedView Change Details
2024-01-18The Error code has changedView Change Details
2023-11-09The Error code has changedView Change Details
2023-09-26The Error code has changedView Change Details