调用 CreateListener 接口，为指定负载均衡实例添加一个监听器。 ## 调用说明 * 创建UDP监听器时，监听端口未被其他UDP监听器监听。 * 创建TCP/HTTP/HTTPS监听器时，监听端口未被其他TCP/HTTP/HTTPS监听器监听。 * CLB实例有未被独占的带宽。若无，请调整已有监听器独占的带宽或者提升CLB实例的规格。 * 四层监听器（TCP和UDP协议）支持将请求转发至IPv4或IPv6的后端服务器。 * 七层监听器（HTTP和HTTPS协议）仅支持将请求转发至IPv4后端服务器。 ## 调试 ## 请求参数 |**名称** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Action |String |是 |CreateListener |要执行的操作，取值为CreateListener。 | |Version |String |是 |2020\-04\-01 |API版本信息，当前版本为：2020\-04\-01。 | |LoadBalancerId |String |是 |clb\-bp1o94dp5i6ea\*\*\*\* |CLB实例的ID。|\ | | | | |您可以调用[DescribeLoadBalancers](https://www.volcengine.com/docs/6406/71772)接口，查询CLB实例ID。 | |ListenerName |String |否 |mylistener |监听器的名称。|\ | | | | ||\ | | | | |* 必须以字母、数字或中文开头，可包含字母、数字、中文及以下特殊字符：点号（.）、下划线（_）和中划线（\-）。|\ | | | | |* 长度限制在1～128字符之间。|\ | | | | |* 不填则默认将“协议\-端口”作为监听器名称。 | |Description |String |否 |This is a listener. |监听器的描述。|\ | | | | ||\ | | | | |* 必须以字母、数字或中文开头，可包含字母、数字、中文及以下特殊字符：英文逗号（,）、点号（.）、下划线（_）、空格（）、等号（=）、中划线（\-）、中文逗号（，）、中文句号（。）。|\ | | | | |* 长度限制为0 ～ 255个字符。|\ | | | | |* 不填则默认值为空字符串。 | |Protocol |String |是 |TCP |监听器的协议。取值如下：|\ | | | | ||\ | | | | |* TCP|\ | | | | |* UDP|\ | | | | |* HTTP|\ | | | | |* HTTPS | |Port |Integer |是 |80 |监听器接收请求使用的端口。取值范围为 0～65535。|\ | | | | |参数`Protocol`为“TCP”或“UDP”时，支持传入0，表示启用全端口监听。|\ | | | | |:::tip|\ | | | | |四层监听器的全端口监听功能正在邀测中，暂仅支持完成 [企业认证](https://www.volcengine.com/docs/6261/64937) 的账号申请试用，如需试用，请联系客户经理。|\ | | | | ||\ | | | | |:::| |StartPort |Integer |否 |80 |全端口监听的起始端口，取值范围为1\-65535。|\ | | | | |参数`Port`为“0”时，该参数必须传入。 | |EndPort |Integer |否 |100 |全端口监听的结束端口，取值范围为1\-65535。|\ | | | | |参数`Port`为“0”时，该参数必须传入，且该参数取值应大于`StartPort`。 | |Scheduler |String |否 |wrr |监听器使用的调度算法。取值如下：|\ | | | | ||\ | | | | |* wrr（默认值）：加权轮询。即权重值越高的后端服务器，被轮询到的次数（概率）越高。|\ | | | | |* wlc：加权最小连接数。即在最少连接数的基础上，根据服务器的不同处理能力，给每个服务器分配不同的权重，使其能够接受相应权值数的服务请求。|\ | | | | |* sh：源地址哈希。即基于源IP地址的一致性哈希，相同的源地址会调度到相同的后端服务器。 | |Bandwidth |Integer |否 |10 |监听器的带宽上限，即此监听器独占CLB实例的带宽，单位为Mbps。|\ | | | | ||\ | | | | |* \-1（默认值）：此监听器不独占CLB的带宽，与其他监听器共享CLB实例未被独占的带宽。|\ | | | | |* 取值范围：1～CLB实例未被独占的带宽。 CLB实例的规格带宽请参见[产品规格](https://www.volcengine.com/docs/6406/68063#%E4%BA%A7%E5%93%81%E8%A7%84%E6%A0%BC)。 | |ServerGroupId |String |是 |rsp\-bp1o94dp5i6ea\*\*\*\* |监听器关联的后端服务器组 ID。|\ | | | | |您可以调用[DescribeServerGroups](https://www.volcengine.com/docs/6406/71782)接口，查询后端服务器组ID。 | |CertificateSource |String |否 |clb |证书的来源。|\ | | | | ||\ | | | | |* clb (默认)：CLB上传的证书|\ | | | | |* cert_center：证书中心上传的证书。 | |CertificateId |String |否 |cert\-bp1o94dp5i6ea\*\*\*\* |CLB上传证书的ID。|\ | | | | |您可以调用[DescribeCertificates](https://www.volcengine.com/docs/6406/71799)接口，查询证书ID。 | |CertCenterCertificateId |String |否 |cert\-bp1o94dp5i6eb\*\*\*\* |证书中心上传证书的ID。|\ | | | | |您可以调用[DescribeCertificates](https://www.volcengine.com/docs/6406/71799)接口，查询证书ID。 | |CAEnabled |String |否 |off |是否开启双向认证。|\ | | | | ||\ | | | | |* on：开启。|\ | | | | |* off（默认值）：不开启。 | |CACertificateId |String |否 |pca_leaf_M6gaihuZRcO\*\*\*\* |双向认证的CA证书的ID。|\ | | | | |您可以调用[ListLeafInstances](https://www.volcengine.com/docs/6638/195535)接口，查询证书ID。 | |HealthCheck.Enabled |String |否 |on |监听器是否开启健康检查功能。|\ | | | | ||\ | | | | |* on（默认值）：开启。|\ | | | | |* off：不开启。|\ | | | | ||\ | | | | |:::tip|\ | | | | |仅当本参数的值为 on 时，参数`HealthCheck.****`有效。|\ | | | | ||\ | | | | |:::| |HealthCheck.Interval |Integer |否 |2 |执行健康检查的时间间隔，取值范围为1 ～ 300 ，默认值为2，单位为秒。 | |HealthCheck.Timeout |Integer |否 |2 |健康检查的响应超时时间，表示如果后端服务器在指定的时间内没有正确响应，则判定为健康检查“异常”。|\ | | | | |取值范围为1 ～ 60，默认值为2，单位为秒。|\ | | | | |:::tip|\ | | | | |响应超时时间需小于等于检查时间间隔。|\ | | | | ||\ | | | | |:::| |HealthCheck.HealthyThreshold |Integer |否 |3 |健康检查的健康阈值，表示连续执行指定次数的健康检查，结果均为“正常”的后端服务器将被判定为健康检查“正常”。|\ | | | | |取值范围为2 ～ 10，默认值为3，单位为次。 | |HealthCheck.UnhealthyThreshold |Integer |否 |3 |健康检查的不健康阈值，表示连续执行指定次数的健康检查，结果均为“异常”的后端服务器将被判定为健康检查异常。|\ | | | | |取值范围为2 ～ 10，默认值为3，单位为次。 | |HealthCheck.UdpRequest |String |否 |Request123 |健康检查的请求字符串。|\ | | | | ||\ | | | | |* 只允许包含字母和数字，最大长度限制为64个字符。|\ | | | | |* 当参数`Protocol`配置为UDP，且参数`HealthCheck.Enabled`配置为on时，该参数生效。|\ | | | | |* 参数`HealthCheck.UdpRequest`和`HealthCheck.UdpExpect`的取值只能同时为空或同时不为空。 | |HealthCheck.UdpExpect |String |否 |Expect123 |健康检查的预期响应字符串。|\ | | | | ||\ | | | | |* 只允许包含字母和数字，最大长度限制为64个字符。|\ | | | | |* 当参数`Protocol`配置为UDP，且参数`HealthCheck.Enabled`配置为on时，该参数生效。|\ | | | | |* 参数`HealthCheck.UdpRequest`和`HealthCheck.UdpExpect`的取值只能同时为空或同时不为空。 | |HealthCheck.Method |String |否 |HEAD |监听器健康检查的方法。|\ | | | | |当参数`Protocol`取HTTP或HTTPS，且`HealthCheck.Enabled`取on时，本参数生效。取值如下：|\ | | | | ||\ | | | | |* GET（默认值）：服务器需支持GET方法。|\ | | | | |* HEAD：服务器仅返回HEAD头部信息，可以降低后端开销，但要求服务器支持HEAD方法。 | |HealthCheck.Domain |String |否 |www.test.com |健康检查的域名，需配置为后端服务器上真实对外提供服务的地址。|\ | | | | ||\ | | | | |* 当参数`Protocol`取HTTP或HTTPS，且`HealthCheck.Enabled`取on时，本参数生效。|\ | | | | |* 需至少包含一个点号（.），且不允许以点号（.）开头或结尾。|\ | | | | |* 单个字符串由字母、数字、中划线（\-）、点号（.）字符组成，中划线（\-）不得出现在字符串的头部或尾部。|\ | | | | |* 长度限制为1 ～ 128个字符。|\ | | | | |* 不传入该参数或该参数不传入数值时，默认为空，表示负载均衡使用各后端服务器的私网IP地址进行健康检查。 | |HealthCheck.URI |String |否 |/test |健康检查的路径，需配置为后端服务器上真实对外提供服务的地址。|\ | | | | ||\ | | | | |* 当参数`Protocol`取HTTP或HTTPS，且`HealthCheck.Enabled`取on时，本参数生效。|\ | | | | |* 必须以字符‘/’开头。|\ | | | | |* 仅包含字母、数字、中划线（\-）、下划线（_）、斜线（/）、点号（.）、百分号（%）、英文问号（?）、#、&、等号（＝）字符。|\ | | | | |* 长度限制为1 ～ 128个字符。|\ | | | | |* 不传入该参数或该参数不传入数值时，默认为“/”。 | |HealthCheck.HttpCode |String |否 |"http_2xx,http_3xx" |健康检查正常的HTTP状态码。|\ | | | | |当参数`Protocol`取HTTP或HTTPS，且`HealthCheck.Enabled`取on时，本参数生效。取值如下：|\ | | | | ||\ | | | | |* http_2xx （默认值）|\ | | | | |* http_3xx|\ | | | | |* http_4xx|\ | | | | |* http_5xx|\ | | | | ||\ | | | | |多个状态码间用半角逗号“,”分隔。 | |HealthCheck.Port |Integer |否 |80 |健康检查的端口，取值范围为1\-65535。|\ | | | | ||\ | | | | |* 参数`Port`为“0”且参数`HealthCheck.Enabled`为“on”时，该参数必须传入。|\ | | | | |* 参数`Port`为不为“0”时，本参数无需传入，系统默为后端服务器的应用端口为健康检查端口。 | |EstablishedTimeout |Integer |否 |800 |监听器的连接超时时间。|\ | | | | |仅参数`Protocol`取TCP或UDP时，本参数有效。取值如下：|\ | | | | ||\ | | | | |* TCP协议：10\-900秒，默认为900秒。|\ | | | | |* UDP协议：1\-300秒，默认为90秒。 | |ClientHeaderTimeout |Integer |否 |60 |读取客户端请求头的超时时间。客户端向CLB发起请求，若在超时时间内客户端没有传输整个报头，CLB将返回408错误码给客户端，表示请求超时。|\ | | | | ||\ | | | | |* 取值范围为30\-120秒。默认为60秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |ClientBodyTimeout |Integer |否 |60 |读取客户端请求正文的超时时间。客户端向CLB发起请求，若在超时时间内客户端没有发送任何请求体，CLB将返回408错误码给客户端，表示请求超时。|\ | | | | ||\ | | | | |* 此超时时间仅针对两个连续的读操作之间设置，而非整个请求的传输过程。|\ | | | | |* 取值范围为 30\-120秒，默认为60秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效 | |KeepaliveTimeout |Integer |否 |60 |客户端与CLB之间的长连接超时时间。若在超时时间内一直没有访问请求，CLB会中断当前连接，直到下一次请求到来时重新建立新的连接。|\ | | | | ||\ | | | | |* 取值范围为 0\-900秒，默认为75秒。|\ | | | | |* 0表示禁用长连接。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |ProxyConnectTimeout |Integer |否 |60 |CLB与后端服务器之间的连接建立超时时间。若超时时间内CLB与后端服务器连接未建立，则终止建立连接操作。|\ | | | | ||\ | | | | |* 建议大于健康检查超时时间。|\ | | | | |* 取值范围为 4\-120秒，默认为4秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |ProxySendTimeout |Integer |否 |60 |CLB将请求传输到后端服务器的超时时间。CLB向后端服务器发起请求，若后端服务器在超时时间内未收到任何内容，则会关闭此连接。|\ | | | | ||\ | | | | |* 此超时仅针对两个连续的写操作之间设置，而非整个请求的传输过程。|\ | | | | |* 取值范围为30\-3600秒，默认为60秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |ProxyReadTimeout |Integer |否 |60 |CLB从后端服务器读取响应的超时时间。CLB向后端服务器发起请求，若超时时间内接收请求的后端服务器无响应，则会关闭此连接。|\ | | | | ||\ | | | | |* 此超时时间仅针对两个连续的读操作之间设置，而非整个响应的传输过程。|\ | | | | |* 取值范围为30\-3600秒，默认为60秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |SendTimeout |Integer |否 |60 |CLB向客户端发送响应的超时时间。CLB向客户端发送响应，若客户端在超时时间内未收到任何内容，则连接会被关闭。|\ | | | | ||\ | | | | |* 此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。|\ | | | | |* 取值范围为 1\-3600秒，默认为60秒。|\ | | | | |* 仅参数`Protocol`取HTTP或HTTPS时，本参数有效。 | |SecurityPolicyId |String |否 |default_policy |HTTPS监听器的TLS安全策略。|\ | | | | ||\ | | | | |* 仅参数`Protocol`取HTTPS时，本参数有效。取值如下：|\ | | | | |* default_policy（默认值）：支持SSL v3、TLS v1.0、TLS v1.1、TLS v1.2。|\ | | | | |* tls_cipher_policy_1_0：支持TLS v1.0、TLS v1.1、TLS v1.2。|\ | | | | |* tls_cipher_policy_1_1：支持TLS v1.1、TLS v1.2。|\ | | | | |* tls_cipher_policy_1_2：支持TLS v1.2。|\ | | | | |* tls_cipher_policy_1_2_strict：支持TLS v1.2。|\ | | | | ||\ | | | | |:::tip|\ | | | | ||\ | | | | |* 以上TLS安全策略支持的加密套件详情请参见[创建HTTPS协议监听器](https://www.volcengine.com/docs/6406/73579)。|\ | | | | |* 不填则默认按照`ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5`配置生效。|\ | | | | ||\ | | | | |:::| |AclStatus |String |否 |off |是否开启访问控制功能。取值如下：|\ | | | | ||\ | | | | |* on：开启。|\ | | | | |* off（默认值）：不开启。 | |AclType |String |否 |black |访问控制的方式。取值如下:|\ | | | | ||\ | | | | |* white：白名单。监听器监听CLB的流量时，CLB仅转发其白名单关联访问控制策略组中IP地址的请求。|\ | | | | |* black（默认值）：黑名单。监听器监听CLB的流量时，对于白名单关联访问控制策略组中IP地址的请求，CLB拒绝转发。|\ | | | | ||\ | | | | |:::tip|\ | | | | |当参数`AclStatus`取 **on** 时，`AclType`和`AclIds.N`为必填。|\ | | | | ||\ | | | | |:::| |AclIds.N |String |否 |AclIds.1=acl\-3cj44nv0jhhxc6c6rrtet\*\*\*\*&AclIds.2=acl\-2febxt4pu0zy85oxruw0t\*\*\*\* |监听器绑定的访问控制策略组ID。|\ | | | | |您可以调用[DescribeAcls](https://www.volcengine.com/docs/6406/71791)接口获取访问控制策略组ID。|\ | | | | ||\ | | | | |* 参数 \- N：表示访问控制策略组的序号，数量上限为5个。|\ | | | | |* 多个访问控制策略组ID间使用“&”分隔。|\ | | | | ||\ | | | | |:::tip|\ | | | | |当参数`AclStatus`取 **on** 时，`AclType`和`AclIds.N`为必填。|\ | | | | ||\ | | | | |:::| |ProxyProtocolType |String |否 |off |是否启用Proxy\-Protocol协议。|\ | | | | |仅参数`Protocol`取TCP或UDP时，本参数有效。取值如下：|\ | | | | ||\ | | | | |* off（默认值）：关闭。|\ | | | | |* standard：开启。 | |PersistenceType |String |否 |off |会话保持的类型。取值如下：|\ | | | | ||\ | | | | |* off（默认值）：不启用会话保持。|\ | | | | |* source_ip：源地址IP，仅参数`Protocol`取TCP或UDP时，本取值有效。|\ | | | | |* insert：植入Cookie，仅参数`Protocol`取HTTP或HTTPS且`Scheduler`取wrr时，本取值生效。|\ | | | | |* server：重写Cookie，仅参数`Protocol`取HTTP或HTTPS且`Scheduler`取wrr时，本取值生效。。 | |PersistenceTimeout |Integer |否 |10 |会话保持的超时时间。单位为秒。默认值为1000秒，取值范围根据参数`PersistenceType`取值有所不同。|\ | | | | ||\ | | | | |* `PersistenceType`配置为source_ip时，取值范围为1～3600。|\ | | | | |* `PersistenceType`配置为insert时，取值范围为1～86400。|\ | | | | ||\ | | | | |:::tip|\ | | | | |参数`PersistenceType`配置为source_ip或insert时，本参数有效。|\ | | | | ||\ | | | | |:::| |Cookie |String |否 |cookie123 |后端服务器配置的会话保持的Cookie名称。|\ | | | | ||\ | | | | |* 仅参数`PersistenceType`取server时，本参数有效且必填。|\ | | | | |* 只能包含字母、数字、下划线（_）和中划线（\-）。|\ | | | | |* 长度限制在1～200字符之间。 | |Http2Enabled |String |否 |off |监听器是否开启前端HTTP 2.0协议。|\ | | | | |仅参数`Protocol取HTTPS时，本参数有效。取值如下：\||\ | | | | ||\ | | | | |* on：开启。|\ | | | | |* off（默认值）：不开启。 | |ConnectionDrainEnabled |String |否 |on |监听器是否开启连接优雅中断功能。|\ | | | | |仅参数`Protocol`取TCP或UDP时，本参数有效。取值如下：|\ | | | | ||\ | | | | |* on：开启。|\ | | | | |* off（默认值）：不开启。 | |ConnectionDrainTimeout |Integer |否 |2 |连接优雅中断的超时时间。取值范围为0～900，单位为秒。|\ | | | | ||\ | | | | |* 参数`ConnectionDrainEnabled`取on时，本参数为必填。|\ | | | | |* 参数`ConnectionDrainEnabled`取off时，本参数默认为0。 | |Enabled |String |否 |on |是否启用监听器。取值如下:|\ | | | | ||\ | | | | |* on（默认值）：开启。|\ | | | | |* off：不开启。 | |Tags.N.Key |String |否 |Tags.1.Key=key1&Tags.2.Key=key2 |用户标签的标签键。|\ | | | | ||\ | | | | |* 参数 \- N：表示标签键的序号，取值范围：1～20。|\ | | | | |* 多个标签键之间用&分隔。|\ | | | | |* 不能以 `volc:`或`sys:`开头，包括任意大小写形式。|\ | | | | |* 长度取值范围为1~128字符，允许输入各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、中划线（\-）和@（@）。|\ | | | | |* 若标签键开头或结尾存在空格，系统会自动为其去除。|\ | | | | ||\ | | | | |:::tip|\ | | | | |同一资源的标签键不允许重复。|\ | | | | ||\ | | | | |:::| |Tags.N.Value |String |否 |Tags.1.Value=value1&Tags.2.Value=value2 |用户标签的标签值。|\ | | | | ||\ | | | | |* 参数 \- N：表示标签值的序号，取值范围：1～20。|\ | | | | |* 多个标签值之间用&分隔。|\ | | | | |* 长度取值范围为0～256字符，不填默认为空。|\ | | | | |* 允许输入各国语言文字、数字、空格（）、下划线（_）、点号（.）、半角冒号（:）、斜杠（/）、等号（=）、加号（+）、中划线（\-）和@（@）。|\ | | | | |* 大小写敏感。|\ | | | | |* 若标签值开头或结尾存在空格，系统会自动为其去除。|\ | | | | ||\ | | | | |:::tip|\ | | | | |若传入该参数，则必须先传入`Tags.N.Key`。|\ | | | | ||\ | | | | |:::| ## 返回参数 |名称 |类型 |示例值 |描述 | |---|---|---|---| |RequestId |String |20210811152539010225146063030\*\*\*\* |请求ID。 | |ListenerId |String |lsn\-2fek3rgsxhrsw5oxruwec\*\*\*\* |监听器ID。 | ## 请求示例 ```json GET /?Action=CreateListener&Version=2020-04-01&AclIds.1=acl-3cj44nv0jhhxc6c6rrtet****&AclStatus=on&AclType=black&Enabled=on&EstablishedTimeout=122&ListenerName=mylistener&LoadBalancerId=clb-bp1o94dp5i6ea****&Port=12&Protocol=TCP&Scheduler=wrr&ServerGroupId=rsp-bp1o94dp5i6ea**** HTTP/1.1 Host: open.volcengineapi.com Region: cn-beijing Service: clb ``` ## 返回示例 ```json { "ResponseMetadata": { "RequestId": "20210811152539010225146063030****", "Action": "CreateListener", "Version": "2020-04-01", "Service": "clb", "Region": "cn-beijing" }, "Result": { "RequestId": "20210811152539010225146063030****", "ListenerId": "lsn-2fek3rgsxhrsw5oxruwec****" } } ``` ## 错误码下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见[公共错误码](https://www.volcengine.com/docs/6406/71761)文档。 |

HttpCode

|错误码 |错误信息 |描述 |\ |---|---|---|---| | | | | | |

400

400

400

400

|InvalidCACertificate.UnSupportAction |The specified CACertificate does not support this action, due to the content of the ca certificate is illegal. |指定的 CA 证书由于内容不合法，不支持当前操作。 |\ | | | | | |

400

400

400

400

400

400

|InvalidCertificateSource.CertCenterCertificateIdMismatch |The specified CertificateSource not match with CertCenterCertificateId. |指定的 CertificateSource 与 CertCenterCertificateId 不一致。 |\ | | | | | |

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

400

|OperationFailed.QueryCertificateService |The request for the specified resource operation failed due to an abnormal access issue with the certificate center service. |由于证书中心服务的访问异常，对指定资源的操作请求失败。 |\ | | | | | |

400

|OperationFailed.QueryPcaService |The request for the specified resource operation failed due to an abnormal access issue with the pca service. |由于证书中心 PCA 服务的访问异常，对指定资源的操作请求失败。 |\ | | | | | |

400

|QuotaExceed.ListenerNumberEachAcl |You've reached the limit on the number of listeners that you can associate. |已达到 ACL 可关联的监听器的数量的配额上限{_tag_}。 |\ | | | | | |

400

403

403

403

403

403

403

403

404

404

404

404

404

404

404

409

409

412

412

412