You need to enable JavaScript to run this app.
导航
DescribeListeners
最近更新时间:2024.06.04 19:00:19首次发布时间:2021.08.31 10:37:27

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

调试

请求参数

名称
类型
是否必选
示例值
描述
ActionStringDescribeListeners要执行的操作,取值为DescribeListeners。
VersionString2020-04-01API版本信息,当前版本为: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之间用&分隔。
ListenerNameStringmylistener监听器的名称。

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
  • 传入空字符串时,表示查询标签值为空的监听器。
PageNumberInteger1列表的页码,默认值为1。
PageSizeInteger20分页查询时每页的行数,取值范围为1 ~ 100,默认为10。

返回参数

名称
类型
示例值
描述
RequestIdString20210811152539010225146063030****请求ID
TotalCountInteger50符合条件的监听器总数。
PageNumberInteger1当前页码。
PageSizeInteger20当前分页的行数。
ListenersArray of Struct-符合条件的监听器的详细信息。具体请参见下表“ Listeners ”。

Listeners

名称
类型
示例值
描述
ListenerIdStringlsn-2fek3rgsxhrsw5oxruwec****监听器的ID。
ListenerNameStringlistener-1监听器的名称。
DescriptionStringmylistener监听器的描述。

Protocol

String

TCP

监听器的协议。

  • TCP
  • UDP
  • HTTP
  • HTTPS
PortInteger80监听器接收请求使用的端口。

Scheduler

String

wrr

监听器使用的调度算法。

  • wrr:加权轮询,权重值越高的后端服务器,被轮询到的次数(概率)越高。
  • wlc:加权最小连接数,在最少连接数的基础上,根据服务器的不同处理能力,给每个服务器分配不同的权重,使其能够接受相应权值数的服务请求。
  • sh:源地址哈希,基于源IP地址的一致性哈希,相同的源地址会调度到相同的后端服务器。

Bandwidth

Integer

10

监听器的带宽峰值,单位为Mbps。
返回为-1,表示监听器不指定限速。此时监听器的带宽峰值默认为CLB实例规格的剩余带宽。

ServerGroupIdStringrsp-bp1o94dp5i6ea****TCP/UDP监听器关联的后端服务器组的ID。HTTP/HTTPS监听器关联的默认后端服务器组ID。
CertificateIdStringcert-bp1o94dp5i6ea****HTTPS监听器关联的证书ID。
HealthCheckStruct-健康检查相关的参数,不同协议所需参数不同。具体请参见如下“ 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

是否启用PP协议。取值如下:

  • off:关闭。
  • standard:开启。

PersistenceType

String

off

会话保持的类型。

  • off:表示不启用会话保持。
  • source_ip:表示源地址IP。
  • insert:表示植入Cookie。
  • server:表示重写Cookie。
PersistenceTimeoutInteger10会话保持的超时时间,单位为秒。
CookieStringcookie123后端服务器配置的会话保持的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:不开启。
TagsArray of Struct-标签信息。具体请参见下表“Tags”。
CreateTimeString2021-08-11T16:37:37Z监听器的创建时间。
UpdateTimeString2021-08-11T16:37:37Z监听器的最近操作时间。

HealthCheck

名称
类型
示例值
描述

Enabled

String

off

监听器是否开启健康检查功能。

  • on :开启。
  • off:不开启。

UdpRequest

String

Request123

执行健康检查的请求字符串。
仅当UDP监听器指定请求字符串时返回该参数。

UdpExpect

String

Expect123

健康检查的预期响应字符串。
仅当UDP监听器指定请求字符串时返回该参数。

IntervalInteger2执行健康检查的时间间隔。
TimeoutInteger2健康检查的响应超时时间,表示如果后端服务器在指定的时间内没有正确响应,则判定为健康检查异常。
HealthyThresholdInteger3健康检查的健康阈值,表示连续执行指定次数的健康检查,结果均为“正常”的后端服务器将被判定为健康检查“正常”。
UnHealthyThresholdInteger3健康检查的不健康阈值,表示连续执行指定次数的健康检查,结果均为“异常”的后端服务器将被判定为健康检查“异常”。

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监听器不返回该参数。

Tags

名称
类型
示例值
描述
KeyStringk1标签的标签键。
ValueStringv1标签的标签值。

请求示例

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,
            "ServerGroupId": "rsp-bp1o94dp5i6ea****",
            "CertificateId": "cert-bp1o94dp5i6ea****",
            "HealthCheck": {
                "Enabled": "on",
                "Interval": 12,
                "Timeout": 0
                "HealthyThreshold": 4,
                "UnHealthyThreshold": 5,
                "Method": "GET",
                "Uri": "/",
                "Domain": "www.test.com",
                "HttpCode": "http_2xx",

            },
            "AclIds": [
                "acl-2fe5excqgk6ww5oxruvcv****",
                "acl-2febxt4pu0zy85oxruw0t****"
            ],
            "ProxyProtocolType": "off",
            "PersistenceType": "off",
            "PersistenceTimeut": 0,
            "Http2Enabled": "off",
            "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
错误码
错误信息
描述
400InvalidName.MalformedThe specified Name is malformed.指定的 Name 参数格式不合法。
400InvalidPaging.MalformedThe specified PageNumber or PageSize is malformed.指定的分页参数格式不合法。
400LimitExceeded.ListenerIdYou've reached the limit on the number of Listener that you can operate.已达到单次可操作 ListenerId 的资源数量上限。
400InvalidIncorrectOrder.MalformedThe specified index order is malformed.指定的索引顺序参数格式不合法。
400InvalidTagKey.MalformedThe specified TagKey is malformed.指定的 TagKey 参数格式不合法。
400InvalidTagValue.MalformedThe specified TagValue is malformed.指定的 TagValue 参数格式不合法。
400LimitExceeded.TagFilterKeyYou've reached the limit on the number of tag keys that you can filter.已达到单次可指定过滤标签键数量的上限。
400LimitExceeded.TagFilterValuesYou've reached the limit on the number of tag values that you can filter.已达到单次可指定过滤标签键值数量的上限。