DocsICP FilingConsole
Documentation

SetLoadBalancerHTTPListenerAttribute

Updated at:
Copy as MD
Product
My Favorites

Modify an HTTP listener's configuration.

Operation description

Prerequisites

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

slb:SetLoadBalancerHTTPListenerAttribute

update

*acl

acs:slb:{#regionId}:{#accountId}:acl/{#aclId}

*loadbalancer

acs:slb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}
  • slb:tag
  • slb:tag
  • slb:tag
 None

Request parameters

Parameter

Type

Required

Description

Example
RegionId

string

No

The region ID of the load balancer instance.

You can get the region ID from the Regions and availability zones list or by calling the DescribeRegions operation.

cn-hangzhou
LoadBalancerId

string

Yes

The ID of the load balancer instance.

lb-bp1qjwo61pqz3ah*****
ListenerPort

integer

Yes

The frontend port used by the load balancer instance.

Value range: 1 to 65535.

80
Bandwidth

integer

No

The peak bandwidth of the listener. Unit: Mbit/s. Valid values:

  • -1: For a pay-by-traffic, Internet-facing load balancer instance, a value of -1 indicates an unlimited listener bandwidth.

  • 1 to 5120: For an Internet-facing, pay-by-bandwidth load balancer instance, specify a peak bandwidth for the listener. The sum of the peak bandwidths of all listeners cannot exceed the peak bandwidth of the instance. For more information, see Share instance bandwidth.

-1
XForwardedFor

string

No

Specifies whether to use the X-Forwarded-For header to retrieve the client's real IP address. Valid values:

  • on (default).

  • off.

on
Scheduler

string

No

The scheduling algorithm. Valid values:

  • wrr: weighted round-robin (WRR). Backend servers with higher weights receive more requests.

  • rr: round-robin (RR). Requests are distributed to backend servers in sequential order.

wrr
StickySession

string

No

Specifies whether to enable sticky sessions. Valid values:

  • on.

  • off.

on
StickySessionType

string

No

The cookie handling method. Valid values:

  • insert: cookie insertion.

When a client makes its first request, the load balancer inserts a SERVERID cookie into the HTTP or HTTPS response. Subsequent requests from the client with this cookie are routed to the same backend server.

  • server: cookie rewriting.

When the load balancer detects a user-defined cookie, it overwrites the original cookie. Subsequent requests from the client with the new cookie are routed to the same backend server.

Note

This parameter is required if you set StickySession to on.

insert
CookieTimeout

integer

No

The cookie timeout period.

Value range: 1 to 86400. Unit: seconds.

Note

This parameter is required if you set StickySession to on and StickySessionType to insert.

500
Cookie

string

No

The cookie that is configured on the backend server.

The value must be 1 to 200 characters long and can contain only ASCII letters and digits. It cannot contain commas (,), semicolons (;), or spaces, and must not start with a dollar sign ($).

Note

This parameter is required if you set StickySession to on and StickySessionType to server.

testCookie
HealthCheck

string

No

Specifies whether to enable health checks. Valid values:

  • on.

  • off.

on
HealthCheckMethod

string

No

The health check method. Valid values: head and get.

Note

This parameter applies only when you set HealthCheck to on.

get
HealthCheckDomain

string

No

The domain name used for health checks. Valid values:

  • $_ip: The private IP of a backend server. If you set this parameter to $_ip or leave it empty, the load balancer uses the private IP of each backend server for the health check.

  • domain: The domain name must be 1 to 80 characters in length and can contain only letters, digits, periods (.), and hyphens (-).

Note

This parameter applies only when you set HealthCheck to on.

172.XX.XX.16
HealthCheckURI

string

No

The URI that is used for health checks.

The URI must be 1 to 80 characters long and can contain letters, digits, and the following special characters: -, /, ., %, ?, #, and &. The URI must start with a forward slash (/) but cannot be a single forward slash.

Note

This parameter applies only when you set HealthCheck to on.

/test/index.html
HealthyThreshold

integer

No

The number of consecutive successful health checks required to change the status of a backend server from fail to success.

Value range: 2 to 10.

Note

This parameter applies only when you set HealthCheck to on.

4
UnhealthyThreshold

integer

No

The number of consecutive failed health checks required to change the status of a backend server from success to fail.

Value range: 2 to 10.

Note

This parameter applies only when you set HealthCheck to on.

4
HealthCheckTimeout

integer

No

The timeout period for a health check response. If a backend ECS instance fails to return a valid response within this timeout period, the health check is considered a failure. This parameter applies only when you set HealthCheck to on.

Value range: 1 to 300. Unit: seconds.

3
HealthCheckInterval

integer

No

The interval between consecutive health checks.

Value range: 1 to 50. Unit: seconds.

Note

This parameter applies only when you set HealthCheck to on.

5
HealthCheckConnectPort

integer

No

The port used for health checks.

Value range: 1 to 65535.

Note

This parameter applies only when you set HealthCheck to on.

8080
HealthCheckHttpCode

string

No

The HTTP status codes that indicate a successful health check. Separate multiple status codes with commas (,).

Valid values: http_2xx, http_3xx, http_4xx, and http_5xx.

Note

This parameter applies only when you set HealthCheck to on.

http_2xx,http_3xx
VServerGroup

string

No

Specifies whether to use a VServer group. Valid values:

  • on.

  • off.

on
VServerGroupId

string

No

The ID of the VServer group.

rsp-cige6j*****
XForwardedFor_SLBIP

string

No

Specifies whether to use the SLB-IP header to retrieve the virtual IP address (VIP) requested by the client. Valid values:

  • on.

  • off.

on
XForwardedFor_SLBID

string

No

Specifies whether to use the SLB-ID header to retrieve the ID of the load balancer instance. Valid values:

  • on.

  • off.

on
XForwardedFor_proto

string

No

Specifies whether to use the X-Forwarded-Proto header to retrieve the listener protocol of the load balancer instance. Valid values:

  • on.

  • off.

on
Gzip

string

No

Specifies whether to enable Gzip compression to compress specific file types. Valid values:

  • on.

  • off.

on
AclId

string

No

The ID of the access control list (ACL) that is associated with the listener.

Note

This parameter is required if you set AclStatus to on.

acl-uf60jw******
AclType

string

No

The type of access control. Valid values:

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the ACL are forwarded. Whitelists are suitable for scenarios where you want to allow access only from specific IP addresses. If you enable a whitelist but do not add any IP addresses to the ACL, the listener forwards all requests.

  • black: a blacklist. All requests from the IP addresses or CIDR blocks in the ACL are denied. Blacklists are suitable for scenarios where you want to deny access from specific IP addresses.

If you enable a blacklist but do not add any IP addresses to the ACL, the listener forwards all requests.

Note

This parameter applies only when you set AclStatus to on.

white
AclStatus

string

No

Specifies whether to enable access control. Valid values:

  • on.

  • off.

off
IdleTimeout

integer

No

The idle connection timeout period. Value range: 1 to 60. Default value: 15. Unit: seconds.

If a connection remains idle for longer than the timeout period, the load balancer closes it. A new connection is established when the next request is received.

12
RequestTimeout

integer

No

The request timeout period. Value range: 1 to 180. Default value: 60. Unit: seconds.

If a backend server fails to respond within this timeout period, the load balancer returns an HTTP 504 error to the client.

3
Description

string

No

A description for the listener.

test
XForwardedFor_SLBPORT

string

No

Specifies whether to use the XForwardedFor_SLBPORT header to retrieve the listener port of the load balancer instance. Valid values:

  • on.

  • off.

off
XForwardedFor_ClientSrcPort

string

No

Specifies whether to use the XForwardedFor_ClientSrcPort header to retrieve the client's source port. Valid values:

  • on.

  • off.

off

Response elements

Element

Type

Description

Example

object

RequestId

string

The request ID.

CEF72CEB-54B6-4AE8-B225-F876FF7BA984

Examples

Success response

JSON format

{
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876FF7BA984"
}

Error codes

HTTP status code

Error code

Error message

Description
400 IpVersionConflict The ip version of this LoadBalancer and the Acl is conflict.
400 Operation.NotAllowed Operation Denied. The HTTP listener does not support this action.
400 InvalidParameter.IdleTimeout The specified IdleTimeout exceeds the limit.
400 InvalidParameter.RequestTimeout The specified RequestTimeout exceeds the limit.
400 ListenerForwardNotSupport X-Forward-For is not supported to a ipv6 instance.
400 InvalidParameter.RegionNotSupport The region does not support the parameter: %s.
400 OperationFailed.ServerGroupInUse The VServerGroup or MasterSlaveServerGroup can not be close for this listener.
400 InvalidParameter.VServerGroupId The MasterSlaveServerGroup can not be attached to HTTP or HTTPS listener.
400 MissingParam.HealthCheckDomain The HealthCheckDomain is required when HealthCheckHttpVersion is http1.1.
400 InvalidParameter.HealthCheckHttpVersion The param HealthCheckHttpVersion is invalid.
400 Duplicated.AclEntry %s. %s
400 InvalidParameter.ForwardCode The specified ForwardCode is invalid.
400 AclListenerOverLimit This acl has reached the limit of binding to listeners.
400 QuotaLimitExceeds.AclAttachedToListener The number of Acl bound listeners has reached the quota limit
400 QuotaLimitExceeds.TotalAclEntry The number of Acl entries has reached the quota limit.
400 QuotaLimitExceeds.AclListenerOverLimit This acl has reached the limit of binding to listeners.
400 DryRunOperation Request validation has been passed with DryRun flag set. Request validation has been passed with DryRun flag set.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.