DescribeListeners--负载均衡-火山引擎

文档中心

立即注册

导航

DescribeListeners

最近更新时间：2024.11.15 09:40:13首次发布时间：2021.08.31 10:37:27

调用 DescribeListeners 接口，查询满足指定条件的监听器。

调用说明

传入多个请求参数，按照传入的参数进行查询，返回符合所有条件的监听器，若没有符合条件的监听器，则返回空值。
若请求参数非必选参数均未传入，则按照当前登录账号查询，返回当前账号下的所有监听器。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

名称	类型	是否必选	示例值	描述
Action	String	是	DescribeListeners	要执行的操作，取值为DescribeListeners。
Version	String	是	2020-04-01	API版本信息，当前版本为：2020-04-01。
LoadBalancerId	String	否	clb-bp1o94dp5i6ea****	负载均衡实例ID。您可以调用DescribeLoadBalancers接口，查询负载均衡实例ID。
ListenerIds.N	String	否	ListenerIds.1=lsn-2fek3rgsxhrsw5oxr** &ListenerIds.2=lsn-2fel9ycnzz94w5ox**	监听器的ID。参数 - N：表示监听器的序号。取值范围：1 ～ 100。多个监听器ID之间用&分隔。
ListenerName	String	否	mylistener	监听器的名称。
Protocol	String	否	TCP	监听器的协议。 TCP UDP HTTP HTTPS
TagFilters.N.Key	String	否	TagFilters.1.Key=k1&TagFilters.2.Key=k2	标签的标签键。参数 - N：表示标签键的序号，取值范围：1～10。多个标签键之间用&分隔。多个标签键之间的关系为逻辑“与（AND）”，即查询同时添加多个标签键的监听器。
TagFilters.N.Values.N	String	否	TagFilters.1.Values.1=v1&TagFilters.1.Values.2=v2&TagFilters.2.Values.1=v3	标签的标签值。第一个N：表示标签键的序号。第二个N：表示标签值的序号，取值范围：1～3。同一标签键多个标签值之间的关系为逻辑“或(OR)”，即查询同一标签键下添加其中一个标签值的监听器。多个标签值之间用&分隔。说明若传入该参数，则必须先传入`TagFilters.N.Key`。传入空字符串时，表示查询标签值为空的监听器。
PageNumber	Integer	否	1	列表的页码，默认值为1。
PageSize	Integer	否	20	分页查询时每页的行数，取值范围为1 ～ 100，默认为10。

返回参数

名称	类型	示例值	描述
RequestId	String	20210811152539010225146063030****	请求ID
TotalCount	Integer	50	符合条件的监听器总数。
PageNumber	Integer	1	当前页码。
PageSize	Integer	20	当前分页的行数。
Listeners	Array of Struct	-	符合条件的监听器的详细信息。具体请参见下表“ Listeners ”。

Listeners

名称	类型	示例值	描述
ListenerId	String	lsn-2fek3rgsxhrsw5oxruwec****	监听器的ID。
ListenerName	String	listener-1	监听器的名称。
Description	String	mylistener	监听器的描述。
Protocol	String	TCP	监听器的协议。
Port	Integer	80	监听端口。 0：开启全端口监听。全端口监听正在邀测中，暂仅支持完成企业认证的账号申请试用，如需试用，请联系客户经理。其他端口：具体的监听端口。
StartPort	Integer	80	全端口监听的起始端口。仅开启全端口监听时，返回此参数。
EndPort	Integer	100	全端口监听的结束端口。仅开启全端口监听时，返回此参数。
Scheduler	String	wrr	监听器使用的调度算法。 wrr：加权轮询，权重值越高的后端服务器，被轮询到的次数（概率）越高。 wlc：加权最小连接数，在最少连接数的基础上，根据服务器的不同处理能力，给每个服务器分配不同的权重，使其能够接受相应权值数的服务请求。 sh：源地址哈希，基于源IP地址的一致性哈希，相同的源地址会调度到相同的后端服务器。
Bandwidth	Integer	10	监听器的带宽峰值，单位为Mbps。返回为-1，表示监听器不指定限速。此时监听器的带宽峰值默认为CLB实例规格的剩余带宽。
ServerGroupId	String	rsp-bp1o94dp5i6ea****	TCP/UDP监听器关联的后端服务器组的ID。HTTP/HTTPS监听器关联的默认后端服务器组ID。
CertificateSource	String	clb	证书的来源。 clb：CLB侧证书管理模块。 cert_center：证书中心。
CertCenterCertificateId	String	cert-bp1o94dp5i6eb****	证书中心的证书的ID。
CertificateId	String	cert-bp1o94dp5i6ea****	CLB侧证书管理模块的证书的ID。
HealthCheck	Struct	-	健康检查相关的参数，不同协议所需参数不同。具体请参见如下“ HealthCheck ”结构。
AclStatus	String	off	是否开启访问控制功能。 on：开启。 off ：不开启。
AclType	String	black	访问控制的方式。 white ：白名单。监听器监听CLB的流量时，CLB仅转发其白名单关联访问控制策略组中IP地址的请求。 black：黑名单。监听器监听CLB的流量时，对于白名单关联访问控制策略组中IP地址的请求，CLB拒绝转发。说明仅`AclStatus`参数为 on 时返回。
AclIds	Array of String	["acl-2fe5excqgk6ww5oxruvcv**","acl-2febxt4pu0zy85oxruw0t**"]	监听器绑定的访问控制策略组ID。说明仅`AclStatus`参数为 on 时返回。
ProxyProtocolType	String	off	是否启用Proxy-Protocol协议。取值如下： off：关闭。 standard：开启。
PersistenceType	String	off	会话保持的类型。 off：表示不启用会话保持。 source_ip：表示源地址IP。 insert：表示植入Cookie。 server：表示重写Cookie。
PersistenceTimeout	Integer	10	会话保持的超时时间，单位为秒。
Cookie	String	cookie123	后端服务器配置的会话保持的Cookie名称。
ClientHeaderTimeout	Integer	60	读取客户端请求头的超时时间。客户端向CLB发起请求，若在超时时间内客户端没有传输整个报头，CLB将返回408错误码给客户端，表示请求超时。仅HTTP/HTTPS监听器返回此参数。
ClientBodyTimeout	Integer	60	读取客户端请求正文的超时时间。客户端向CLB发起请求，若在超时时间内客户端没有发送任何请求体，CLB将返回408错误码给客户端，表示请求超时。此超时时间仅针对两个连续的读操作之间设置，而非整个请求的传输过程。仅HTTP/HTTPS监听器返回此参数。
KeepaliveTimeout	Integer	60	客户端与CLB之间的长连接超时时间。若在超时时间内一直没有访问请求，CLB会中断当前连接，直到下一次请求到来时重新建立新的连接。 0表示禁用长连接。仅HTTP/HTTPS监听器返回此参数。
ProxyConnectTimeout	Integer	60	CLB与后端服务器之间的连接建立超时时间。若超时时间内CLB与后端服务器连接未建立，则终止建立连接操作。仅HTTP/HTTPS监听器返回此参数。
ProxySendTimeout	Integer	60	CLB将请求传输到后端服务器的超时时间。CLB向后端服务器发起请求，若后端服务器在超时时间内未收到任何内容，则会关闭此连接。此超时仅针对两个连续的写操作之间设置，而非整个请求的传输过程。仅HTTP/HTTPS监听器返回此参数。
ProxyReadTimeout	Integer	60	CLB从后端服务器读取响应的超时时间。CLB向后端服务器发起请求，若超时时间内接收请求的后端服务器无响应，则会关闭此连接。此超时时间仅针对两个连续的读操作之间设置，而非整个响应的传输过程。仅HTTP/HTTPS监听器返回此参数。
SendTimeout	Integer	60	CLB向客户端发送响应的超时时间。CLB向客户端发送响应，若客户端在超时时间内未收到任何内容，则连接会被关闭。此超时仅针对两个连续的写操作之间设置，而非整响应的传输过程。仅HTTP/HTTPS监听器返回此参数。
SecurityPolicyId	String	default_policy	HTTPS监听器的TLS安全策略。仅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。说明除default_policy外，以上TLS安全策略支持的加密套件详情请参见创建HTTPS协议监听器。传入default_policy时，按照`ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5`配置生效。
Http2Enabled	String	off	HTTPS协议监听器是否开启前端HTTP 2.0协议。 on：开启。 off：不开启。说明 TCP、UDP和HTTP协议监听器不返回该参数。
ConnectionDrainEnabled	String	on	监听器是否开启连接优雅中断功能。 on：开启。 off：不开启。说明参数`Protocol`返回为HTTP或HTTPS时，该参数固定返回off。
ConnectionDrainTimeout	Integer	2	连接优雅中断的超时时间，单位为秒。说明参数`ConnectionDrainEnabled`返回为off时，该参数返回0。
Status	String	Active	监听器的状态。 Creating：创建中。 Active：运行中。 Deleting: 删除中。 Disabled: 已停用。
Enabled	String	off	是否启用监听器。 on：开启。 off：不开启。
Tags	Array of Struct	-	标签信息。具体请参见下表“Tags”。
CreateTime	String	2021-08-11T16:37:37Z	监听器的创建时间。
UpdateTime	String	2021-08-11T16:37:37Z	监听器的最近操作时间。

HealthCheck

名称	类型	示例值	描述
Enabled	String	off	监听器是否开启健康检查功能。 on ：开启。 off：不开启。
UdpRequest	String	Request123	执行健康检查的请求字符串。仅当UDP监听器指定请求字符串时返回该参数。
UdpExpect	String	Expect123	健康检查的预期响应字符串。仅当UDP监听器指定请求字符串时返回该参数。
Interval	Integer	2	执行健康检查的时间间隔。
Timeout	Integer	2	健康检查的响应超时时间，表示如果后端服务器在指定的时间内没有正确响应，则判定为健康检查异常。
HealthyThreshold	Integer	3	健康检查的健康阈值，表示连续执行指定次数的健康检查，结果均为“正常”的后端服务器将被判定为健康检查“正常”。
UnHealthyThreshold	Integer	3	健康检查的不健康阈值，表示连续执行指定次数的健康检查，结果均为“异常”的后端服务器将被判定为健康检查“异常”。
Method	String	GET	监听器健康检查的方法。 GET：服务器需支持GET方法。 HEAD：服务器仅返回HEAD头部信息，可以降低后端开销，但要求服务器支持HEAD方法。说明 TCP/UDP监听器不返回该参数。
Uri	String	/	健康检查的路径。说明 TCP/UDP监听器不返回该参数。
Domain	String	www.test.com	健康检查的域名。说明 TCP/UDP监听器不返回该参数。
HttpCode	String	http_2xx	健康检查正常的HTTP状态码。 http_2xx http_3xx http_4xx http_5xx 说明 TCP/UDP监听器不返回该参数。
Port	Integer	80	健康检查的后端服务器端口。开启全端口监听时，返回该参数表示健康检查使用的端口。未开启全端口监听时，不返回该参数，健康检查使用后端服务器的业务端口。

名称	类型	示例值	描述
Key	String	k1	标签的标签键。
Value	String	v1	标签的标签值。

请求示例

GET /?Action=DescribeListeners&Version=2020-04-01&LoadBalancerId=clb-bp1o94dp5i6ea****&PageSize=20&PageNumber=1&ListenerIds.1=lsn-2fek3rgsxhrsw5oxr****&ListenerName=test HTTP/1.1
Host: open.volcengineapi.com
Region: cn-beijing
Service: clb

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20210811152539010225146063030****",
        "Action": "DescribeListeners",
        "Version": "2020-04-01",
        "Service": "clb",
        "Region": "cn-beijing"
    },  
    "Result": {
        "RequestId": "20210811152539010225146063030****",
        "TotalCount": 1,        
        "PageNumber": 1,
        "PageSize": 20,
        "Listeners": [
        {
            "ListenerId": "lsn-2fek3rgsxhrsw5oxr****",
            "ListenerName": "test",
            "Protocol": "HTTPS",
            "Scheduler": "wrr",
            "Port": 3,
            "AclStatus": "on",
            "AclType": "black",
            "Bandwidth": -1,
            "AclIds": [
                "acl-2fe5excqgk6ww5oxruvcv****",
                "acl-2febxt4pu0zy85oxruw0t****"
            ],
            "CertificateSource": "clb",
            "CertificateId": "cert-bp1o94dp5i6ea****",
            "ProxyProtocolType": "off",
            "PersistenceType": "off",
            "PersistenceTimeut": 0,
            "Http2Enabled": "off",
            "ServerGroupId": "rsp-bp1o94dp5i6ea****",
            "HealthCheck": {
                "Enabled": "on",
                "Interval": 12,
                "Timeout": 0
                "HealthyThreshold": 4,
                "UnHealthyThreshold": 5,
                "Method": "GET",
                "Uri": "/",
                "Domain": "www.test.com",
                "HttpCode": "http_2xx",

            },
            "ConnectionDrainEnabled": "off",
            "ConnectionDrainTimeout": 0,
            "Status": "Active",            
            "Enabled": "on",
            "Tags": [
                {
                    "Key": "k1",
                    "Value": "v1"
                },
                {
                    "Key": "k2",
                    "Value": ""
                }
            ],
            "CreateTime": "2021-08-14T11:13:40Z",
            "UpdateTime": "2021-08-14T11:13:41Z",
          }
        ]
    }
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

HttpCode	错误码	错误信息	描述
400	InvalidName.Malformed	The specified Name is malformed.	指定的 Name 参数格式不合法。
400	InvalidPaging.Malformed	The specified PageNumber or PageSize is malformed.	指定的分页参数格式不合法。
400	InvalidProtocol.Malformed	The specified Protocol is malformed.	指定的 Protocol 参数格式不合法。
400	LimitExceeded.ListenerId	You've reached the limit on the number of Listener that you can operate.	已达到单次可操作 ListenerId 的资源数量上限。
400	InvalidIncorrectOrder.Malformed	The specified index order is malformed.	指定的索引顺序参数格式不合法。
400	InvalidTagKey.Malformed	The specified TagKey is malformed.	指定的 TagKey 参数格式不合法。
400	InvalidTagValue.Malformed	The specified TagValue is malformed.	指定的 TagValue 参数格式不合法。
400	LimitExceeded.TagFilterKey	You've reached the limit on the number of tag keys that you can filter.	已达到单次可指定过滤标签键数量的上限。
400	LimitExceeded.TagFilterValues	You've reached the limit on the number of tag values that you can filter.	已达到单次可指定过滤标签键值数量的上限。