tencent cloud

Cloud Load Balancer

ドキュメントCloud Load BalancerAPI リファレンスListener APIsModifyListener

ModifyListener

ダウンロード
フォーカスモード
フォントサイズ
最終更新日: 2026-06-17 17:26:59

1. API Description

Domain name for API request: clb.intl.tencentcloudapi.com.

This API is used to modify the attributes of a CLB instance listener, including the listener name, health check parameters, certificate information, and forwarding policy. This API does not support classic CLB instances.
This is an asynchronous API. After it returns the result successfully, you can call the DescribeTaskStatus API with the returned RequestId as an input parameter to query whether the task is successful.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: ModifyListener.
Version Yes String Common Params. The value used for this API: 2018-03-17.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
LoadBalancerId Yes String

ID of the Cloud Load Balancer (CLB) instance. You can call the DescribeLoadBalancers API to query the ID.
ListenerId Yes String

ID of the CLB listener. You can call the DescribeListeners API to query the ID.
ListenerName No String

New listener name. Naming rule: 1-80 characters including English letters, Chinese characters, digits, connecting line "-", underscore "_" and other common characters (Unicode supplementary characters such as emoji and rare Chinese characters are forbidden).
SessionExpireTime No Integer

Session persistence time, unit: second. Available values: 30-3600, default 0, disabled. This parameter is applicable only to TCP/UDP listener.
HealthCheck No HealthCheck

Health check parameters. This parameter is applicable only to TCP/UDP/TCP_SSL/QUIC listeners.
Certificate No CertificateInput

Certificate-related information. This parameter is applicable only to HTTPS/TCP_SSL/QUIC listeners. This parameter and MultiCertInfo cannot be specified at the same time.
Scheduler No String

Listener forwarding method. Valid values: WRR (weighted round-robin), LEAST_CONN (least connections), and IP_HASH (IP address hash).
They indicate weighted round-robin and least connection respectively. Default is WRR.
Usage scenario: Suitable for TCP/UDP/TCP_SSL/QUIC listeners. The balancing method for Layer-7 listeners should be modified in the forwarding rules.
SniSwitch No Integer

Whether to enable SNI feature. This parameter applies only to HTTPS listeners. Default is 0 (disabled) or 1 (enable). Note: You can enable SNI for listeners without SNI. SNI cannot be disabled for listeners with SNI enabled.
TargetType No String

Backend target type. NODE indicates binding to a general node. TARGETGROUP indicates binding to a target group.
KeepaliveEnable No Integer

Whether to enable long connections. This parameter is applicable only to HTTP/HTTPS listeners.
The default value 0 means disabled, and 1 means enable.
If the backend service has a connection limit, enable with caution. This feature is currently in internal testing. If needed, submit a beta application.
DeregisterTargetRst No Boolean

Rescheduling feature, which provides a switch for scaling out the backend service. If the switch is toggled on, rescheduling is triggered when the backend service is unbound. This parameter is applicable only to TCP/UDP listeners.
SessionType No String

Session persistence type. NORMAL means the default session persistence type. QUIC_CID refers to maintaining the session based on Quic Connection ID. QUIC_CID supports only UDP Protocol.
Usage scenario: Applicable to TCP/UDP/TCP_SSL/QUIC listeners.
Default is NORMAL.
MultiCertInfo No MultiCertInfo

Certificate information. Multiple server certificates with different algorithm types can be imported at the same time. This parameter is applicable only to HTTPS listeners with SNI feature disabled. This parameter and Certificate cannot be specified at the same time.
MaxConn No Integer

Maximum number of concurrent connections at the listener level. This parameter is supported only for LCU-supported instances with TCP/UDP/TCP_SSL/QUIC listeners currently. Value range: 1 to the maximum number of concurrent connections for the instance specification. -1 indicates no speed limit on the concurrent connections at the listener level. Classic network instances do not support this parameter.
Default value is -1, which means unlimited speed.
MaxCps No Integer

Maximum number of new connections at the listener level. This parameter is supported only for LCU-supported instances with TCP/UDP/TCP_SSL/QUIC listeners currently. Value range: 1 to the maximum number of new connections for the instance specification. -1 indicates no speed limit on new connections at the listener level. Classic network instances do not support this parameter.
Default is -1, which means unlimited speed.
IdleConnectTimeout No Integer

Idle connection timeout. This parameter applies only to TCP/UDP listeners. To set a value exceeding 1980, submit a ticket for application. The maximum value can be 3600.

Range of values: [10, 1980]

Unit: seconds

Default value: 900

Default value for TCP listeners: 900. Default value for UDP listeners: 300. Value range: 10–900 for shared instances and dedicated instances and 10–1980 for LCU-supported instances.
ProxyProtocol No Boolean

Whether TCP_SSL and QUIC support PP
SnatEnable No Boolean

Whether SNAT (source IP replacement) is enabled, True (enabled), False (disabled). Disabled by default. Note: When SnatEnable is enabled, the client source IP will be replaced. At this point, the Pass through client source IP option is disabled, and vice versa.
DataCompressMode No String

Data compression mode

Enumeration value:

  • transparent: Transparent mode (default value)
  • compatibility: Compatible mode (enable gzip compression configuration)
RescheduleTargetZeroWeight No Boolean

Rescheduling feature, which provides a switch for changing the weight to 0. If the switch is toggled on, rescheduling is triggered when the weight of a real server is changed to 0. This parameter is applicable only to TCP/UDP listeners.
RescheduleUnhealthy No Boolean

Rescheduling feature, which provides a switch for detecting health check exceptions. If the switch is toggled on, rescheduling is triggered when the real server health check fails. This parameter is applicable only to TCP/UDP listeners.
RescheduleExpandTarget No Boolean

Rescheduling feature, which provides a switch for scaling out real servers. If the switch is toggled on, rescheduling is triggered when the number of real servers increases or decreases. This parameter is applicable only to TCP/UDP listeners.
RescheduleStartTime No Integer

Rescheduling trigger start time. Value range: 0–3600. Unit: s. This parameter is applicable only to TCP/UDP listeners.
RescheduleInterval No Integer

Rescheduling trigger duration. Value range: 0–3600. Unit: s. This parameter is applicable only to TCP/UDP listeners.

3. Output Parameters

Parameter Name Type Description
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Modifying the Certificate Bound to an HTTPS Listener

This example shows you how to modify the certificate bound to an HTTPS listener.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyListener
<Common request parameters>

{
    "ListenerId": "lbl-4fbxq45k",
    "Certificate": {
        "SSLMode": "UNIDIRECTIONAL",
        "CertId": "Nb1DY3hQ"
    },
    "LoadBalancerId": "lb-cuxw2rm0"
}

Output Example

{
    "Response": {
        "RequestId": "b64574f9-5bc7-4a63-a9d7-3671b6a6d62b"
    }
}

Example2 Modifying the Name, Health Check Parameters, and Forwarding Policy of a TCP Listener

This example shows you how to modify the name, health check parameters, and forwarding policy of a TCP listener.

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyListener
<Common request parameters>

{
    "HealthCheck": {
        "UnHealthNum": 5,
        "HealthNum": 5,
        "IntervalTime": 60,
        "TimeOut": 35,
        "HealthSwitch": 1
    },
    "LoadBalancerId": "lb-cuxw2rm0",
    "ListenerId": "lbl-d1ubsydq",
    "ListenerName": "newlis",
    "Scheduler": "LEAST_CONN",
    "SessionExpireTime": 120
}

Output Example

{
    "Response": {
        "RequestId": "8cd88c83-fd30-47c0-8e7a-89bf13a7a83c"
    }
}

Example3 Modifying Listener Reschedule Parameters

Input Example

POST / HTTP/1.1
Host: clb.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyListener
<Common request parameters>

{
    "LoadBalancerId": "lb-fd9kpk4s",
    "ListenerId": "lbl-1sf4yxie",
    "RescheduleTargetZeroWeight": false,
    "RescheduleUnhealthy": false,
    "RescheduleExpandTarget": false,
    "RescheduleStartTime": 0,
    "RescheduleInterval": 0
}

Output Example

{
    "Response": {
        "RequestId": "e5854a85-faee-485e-8892-0a7cbca45080"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation Operation failed.
FailedOperation.ResourceInOperating The specified resource is currently being operated. Please try again later.
InternalError Internal error.
InvalidParameter Parameter error.
InvalidParameter.FormatError Incorrect parameter format.
InvalidParameterValue Parameter value error.
InvalidParameterValue.Length Invalid parameter length.
MissingParameter Parameters are missing.
UnauthorizedOperation Unauthorized operation.
前の記事へ: DescribeListeners次の記事へ: ModifyRule

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック