tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
文档

CreateListener

最后更新时间：2024-09-05 19:28:49

    1. API Description

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

    This API is used to create a listener for a CLB instance.
    This is an async API. After it is returned successfully, you can call the DescribeTaskStatus API with the returned RequestId as an input parameter to check whether this 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: CreateListener.
    Version Yes String Common Params. The value used for this API: 2018-03-17.
    Region No String Common Params. This parameter is not required for this API.
    LoadBalancerId Yes String CLB instance ID
    Ports.N Yes Array of Integer Specifies for which ports to create listeners. Each port corresponds to a new listener.
    Protocol Yes String Listener protocol. Values: TCP | UDP | HTTP | HTTPS | TCP_SSL | QUIC
    ListenerNames.N No Array of String List of names of the listeners to be created. The array of names and array of ports are in one-to-one correspondence. If you do not want to name them now, you do not need to provide this parameter.
    HealthCheck No HealthCheck Health check parameter. It is only applicable only to TCP, UDP, TCP_SSL and QUIC listeners.
    Certificate No CertificateInput Certificate information. This parameter is only applicable to TCP_SSL listeners and HTTPS listeners with the SNI feature not enabled. Certificate and MultiCertInfo cannot be specified at the same time.
    SessionExpireTime No Integer Session persistence time in seconds. Value range: 30-3,600. The default value is 0, indicating that session persistence is not enabled. This parameter is applicable only to TCP/UDP listeners.
    Scheduler No String Listener forwarding mode. Values: WRR (weighted round robin) and LEAST_CONN (least connections).
    Default value: WRR. This parameter is only applicable to TCP, UDP, TCP_SSL and QUIC listeners.
    SniSwitch No Integer Whether to enable the SNI feature. This parameter is applicable only to HTTPS listeners
    TargetType No String Target real server type. NODE: binding a general node; TARGETGROUP: binding a target group.
    SessionType No String Session persistence type. Valid values: Normal: the default session persistence type; QUIC_CID: session persistence by QUIC connection ID. The QUIC_CID value can only be configured in UDP listeners. If this field is not specified, the default session persistence type will be used.
    KeepaliveEnable No Integer Whether to enable a persistent connection. This parameter is applicable only to HTTP and HTTPS listeners. Valid values: 0 (disable; default value) and 1 (enable).
    EndPort No Integer This parameter is used to specify the end port and is required when creating a port range listener. Only one member can be passed in when inputting the Ports parameter, which is used to specify the start port. If you want to try the port range feature, please submit a ticket.
    DeregisterTargetRst No Boolean Whether to send the TCP RST packet to the client when unbinding a real server. This parameter is applicable to TCP listeners only.
    MultiCertInfo No MultiCertInfo Certificate information. You can specify multiple server-side certificates with different algorithm types. This parameter is only applicable to HTTPS listeners with the SNI feature not enabled. Certificate and MultiCertInfo cannot be specified at the same time.
    MaxConn No Integer Maximum number of concurrent listener connections. It's available for TCP/UDP/TCP_SSL/QUIC listeners. If it's set to -1 or not specified, the listener speed is not limited.
    MaxCps No Integer Maximum number of new listener connections. It's available for TCP/UDP/TCP_SSL/QUIC listeners. If it's set to -1 or not specified, the listener speed is not limited.
    IdleConnectTimeout No Integer Connection idle timeout period (in seconds). It's only available to TCP listeners. Value range: 300-900 for shared and dedicated instances; 300-2000 for LCU-supported CLB instances. It defaults to 900. To set a period longer than 2000 seconds (up to 3600 seconds), please submit a submit.
    SnatEnable No Boolean
    FullEndPorts.N No Array of Integer

    3. Output Parameters

    Parameter Name Type Description
    ListenerIds Array of String Array of unique IDs of the created listeners
    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 Creating an HTTPS Listener and Binding an Existing Certificate

    This example shows you how to create an HTTPS listener and bind an existing certificate.

    Input Example

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



{
    "Protocol": "HTTPS",
    "Ports": [
        "7572"
    ],
    "Certificate": {
        "SSLMode": "UNIDIRECTIONAL",
        "CertId": "MsJyaXVm"
    },
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-bzfmg9m6"
        ],
        "RequestId": "6082314c-030c-429d-9eae-2dc6b159b5b9"
    }
}

    Example2 Creating a TCP Listener and Configuring the Health Check Settings

    This example shows you how to create a TCP listener and configure the health check settings.

    Input Example

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



{
    "HealthCheck": {
        "UnHealthNum": "4",
        "HealthNum": "4",
        "IntervalTime": "7",
        "TimeOut": "5",
        "HealthSwitch": "1"
    },
    "Protocol": "TCP",
    "Ports": [
        "7571"
    ],
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-4fbxq45k"
        ],
        "RequestId": "db8ae69f-ebda-402b-8d02-ead459aa6ff9"
    }
}

    Example3 Creating an HTTPS Listener and Binding a New Certificate

    This example shows you how to create an HTTPS listener and bind a new certificate.

    Input Example

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



{
    "Protocol": "HTTPS",
    "Ports": [
        "7573"
    ],
    "Certificate": {
        "SSLMode": "UNIDIRECTIONAL",
        "CertContent": "-----BEGINCERTIFICATE-----\\nMIIEjTCCA3WgAwIBAgIQA4ZHUAVOv4yrszl3lLfo3TANBgkqhkiG9w0BAQsFADBy\\nMQswCQYDVQQGEwJDTjElMCMGA1UEChMcVHJ1c3RBc2lhIFRlY2hub2xvZ2llcywg\\nSW5jLjEdMBsGA1UECxMURG9tYWluIFZhbGlkYXRlZCBTU0wxHTAbBgNVBAMTFFRy\\ndXN0QXNpYSBUTFMgUlNBIENBMB4XDTE4MDEwOTAwMDAwMFoXDTE5MDEwOTEyMDAw\\nMFowFjEUMBIGA1UEAxMLZmx5Zmx5Lm5hbWUwggEiMA0GCSqGSIb3DQEBAQUAA4IB\\nDwAwggEKAoIBAQClpnigB7r3ahv7BMuQw9KzB9Yfq3p+cRUbX9EMRyri2GrJbmrP\\npESP8XQuIn4MZESvePR0r4gGHAHVri8nXzyQw6/m77BT/fIf4cQtEyz61gopDlYq\\nbLTAKVfGFhGVikvQPoItOYbA9/l2YwtDENl8wBhcFrghWTRifnFSC0bNPj1ot5eu\\nL8x5UOZLSa9kaQCm2/RQUBii5w3YBh+HmJgb7HPs8OoHKVScBo6eAyOcr+HNrA8W\\nKsM6r4LpS+Rpfng7+fAKGE+vFsssXfRMBTo0TPp+h8ohuM8xqujbK+T7LMEXNWN9\\n3FGYuuH+qmPvx/gAXFjLARKVyf0IsNnu6TLLAgMBAAGjggF5MIIBdTAfBgNVHSME\\nGDAWgBR/05nzoEcOMQBWViKOt8ye3coBijAdBgNVHQ4EFgQUUCq9/Hmfgli5URvx\\nAbSDNsDCCqcwJwYDVR0RBCAwHoILZmx5Zmx5Lm5hbWWCD3d3dy5mbHlmbHkubmFt\\nZTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\\nMEwGA1UdIARFMEMwNwYJYIZIAYb9bAECMCowKAYIKwYBBQUHAgEWHGh0dHBzOi8v\\nd3d3LmRpZ2ljZXJ0LmNvbS9DUFMwCAYGZ4EMAQIBMIGBBggrBgEFBQcBAQR1MHMw\\nJQYIKwYBBQUHMAGGGWh0dHA6Ly9vY3NwMi5kaWdpY2VydC5jb20wSgYIKwYBBQUH\\nMAKGPmh0dHA6Ly9jYWNlcnRzLmRpZ2l0YWxjZXJ0dmFsaWRhdGlvbi5jb20vVHJ1\\nc3RBc2lhVExTUlNBQ0EuY3J0MAkGA1UdEwQCMAAwDQYJKoZIhvcNAQELBQADggEB\\nADstNGgqYXG6eBDcBGVZk6DnJdS4GYdSzFZgCwt298cPMmZj107VM0QsB5K8V5Zd\\nzJl5c7o4tEXiGP+lk0TVqgP/CkcMXcpxeKB94ldyX9ILii/L4hI9j7hVrLVM1eAn\\nfS66Yg65xIYU8PdFtP3uhI9WdhE3nYRngyoHAAMjIvu0bqGPYbqpnHYp8fmjyetF\\nC9CZcjkqHmwTSpjXuFjbDLx/BXd1Q81TNXwv8alkuXKfIJ5tW2lH372GmQb8I3oI\\nPREP38tlBbmfEu4p7+UzwwuQuD8cEUVuG/x7cUN2uAGiZGoohydrORWm8kqdNY9c\\nYOuRvokzVT4lsaln5LKkKxw=\\n-----ENDCERTIFICATE-----",
        "CertName": "my-cert",
        "CertKey": "-----BEGINRSAPRIVATEKEY-----\\nMIIEoAIBAAKCAQEApaZ4oAe692ob+wTLkMPSswfWH6t6fnEVG1/RDEcq4thqyW5q\\nz6REj/F0LiJ+DGREr3j0dK+IBhwB1a4vJ188kMOv5u+wU/3yH+HELRMs+tYKKQ5W\\nKmy0wClXxhYRlYpL0D6CLTmGwPf5dmMLQxDZfMAYXBa4IVk0Yn5xUgtGzT49aLeX\\nri/MeVDmS0mvZGkAptv0UFAYoucN2AYfh5iYG+xz7PDqBylUnAaOngMjnK/hzawP\\nFirDOq+C6UvkaX54O/nwChhPrxbLLF30TAU6NEz6fofKIbjPMaro2yvk+yzBFzVj\\nfdxRmLrh/qpj78f4AFxYywESlcn9CLDZ7ukyywIDAQABAoH/KoiULD7g9kAEZrQp\\n1SQusYVRl+E8xeVUdQhHcfCyAUkIAEpZzV2TtLd+DFqKrbTvITBT+vd9sYtdU6K7\\nZ8cMcMoSpNMq+/+wK/b/m4I/6EqEt8HDb0NpSBBEeWUxQM4fumnsFBcXtew6iCtu\\n2vzN7G2IwqUSxI5nbY2SektZ4q5ZRvwEND6gE51uqcqo4i6hA/TYsJLZ63L+Ux0A\\nnm0AsmtMct+DT13NAlpyi6feDQCr1cxcSpqfhfgkWpawJVSxtxKvIn044iRBXb7Y\\nRcW/8YYU1PrTIhhE9AnES7g8mnAgBHRryxuUotXkk7VotTHDbTO0q5KvO2bZ2T6z\\nvQ4BAoGBANqoZE/wAB41wbJ7KwyblxyegI3Y9XYtkPLZlLK+GbCaC9UHNhPqSdaH\\nWPoc3rtm8tOFQc7QMTFtxTLwQ3wEeSO4BFckVHgywuJoGRw1ZYxN8vAzHF1Gc/J1\\nYcX0CDBuKgc0CxlhM7tDAzOgcfJR0EFRVhvLcUAA9hUoeN3EetSBAoGBAMHwnjWc\\n+Y/vBW5yCefQciqppaylwB89H6kds+p0fDlVZQ080VB3b61t6VXOoYAzY4abOjxK\\nAfNyVQcOEuO3gtZp3THK3fkV6bKaNHG41Ang32VW3XGb+MeEkJZwJk4JFbLrz8ln\\nte4M9PjVpYuEQCJZvUjrhd+LJRubTTUXIHFLAoGAU0KJp/KwaNB5aDgERXG9kbU9\\nKEYz+YMSTZbSS1mduKR/2uc7DUxKP3kcRWjW2y8xSZ/VViXqhXLSAzp/x+qAIjzA\\n0lnQHFDf6oxO+3HNsCZCWnpr04yvO+S8jT8GG0LnmASWMVzU8Ppsbq0qlmXW0fhh\\nvIW0IvX6vkXB+FgHmYECgYBrsJe5P4QYV2oVrP8xGL78T51uY89tyTwWZSbtTmdY\\nUsG8+wNjgh6iF8EUY5usG1ztdq58ob+5lcf/FeKJTfI56yjnKDXfxToycYwjhbVA\\nEv0ZQYXPOwOGjmbXEklC1aqV4nlL5enQ2KMCtWeqM/KE4H3JyvZYbeRaEv9pNoFO\\nRwKBgBs+g0d81ufZSuTBlxfivDwrNV6LNzrgnwsTn+H/T7MfyoIEkT3nSGjanQHF\\nwzPYyUpQx5OzNZp1ZEzKeW3GXVWjK+bfKlA7fmrZwDa8/JR6kTfCmc3WRrrQ92yq\\nlFRW1kinLCP5y56SJEBz+DRSYV7ql9wOHyaM23sHkbCF0HAa\\n-----ENDRSAPRIVATEKEY-----"
    },
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-lbbxvq26"
        ],
        "RequestId": "fff13c83-dcb5-481a-ba7c-30e92c276c19"
    }
}

    Example4 Creating a UDP Listener with the Default Ping Health Check

    This example shows you how to create a UDP listener with the default Ping health check.

    Input Example

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



{
    "HealthCheck": {
        "HealthSwitch": "1"
    },
    "Protocol": "UDP",
    "ListenerNames": [
        "lis_test"
    ],
    "Ports": [
        "432"
    ],
    "LoadBalancerId": "lb-6wlxe9rj"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-aev333n1"
        ],
        "RequestId": "3b81f03e-6088-448d-abaf-8a487d4f985a"
    }
}

    Example5 Creating Two TCP Listeners (Respectively Named lis0 and lis1) to Respectively Listen on Ports 7569 and 7570

    This example shows you how to create two TCP listeners (respectively named lis0 and lis1) to respectively listen on ports 7569 and 7570.

    Input Example

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



{
    "ListenerNames": [
        "lis1",
        "lis0"
    ],
    "Protocol": "TCP",
    "Ports": [
        "7570",
        "7569"
    ],
    "LoadBalancerId": "lb-cuxw2rm0"
}

    Output Example

    {
    "Response": {
        "ListenerIds": [
            "lbl-d1ubsydq",
            "lbl-4udz130k"
        ],
        "RequestId": "8f272cef-14ff-458c-b67e-1bd21bd2942b"
    }
}

    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 Wrong parameter format.
    InvalidParameter.PortCheckFailed Listener port checks failed due to port conflicts or other reasons.
    InvalidParameterValue Incorrect parameter value.
    InvalidParameterValue.Length Wrong parameter length.
    LimitExceeded Quota exceeded.
    MissingParameter Missing parameter.
    ResourceInsufficient Insufficient resources.
    UnauthorizedOperation Unauthorized operation.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    隐私条款服务条款缓存条款