接口约束
4.10 监听器
4.10.2 查询监听器列表
"transparent_client_ip_enable" : false
}, "request_id" : "f4c4aca8-df16-42e8-8836-33e4b8e9aa8e"
}
状态码
状态码 描述
201 POST操作正常返回。
错误码
请参见错误码。
4.10.2 查询监听器列表
功能介绍
查询监听器列表。
接口约束
● 分页查询使用的参数为marker、limit、page_reverse。
● marker和page_reverse只有和limit一起使用时才会生效，单独使用无效。
调试
您可以在API Explorer中调试该接口。
URI
GET /v3/{project_id}/elb/listeners
表4-228 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 项目ID。
表4-229 Query 参数
参数 是否必选 参数类型 描述
limit 否 Integer 每页返回的个数。
最小值：0 最大值：2000 缺省值：2000
marker 否 String 上一页最后一条记录的ID。
使用说明：
● 必须与limit一起使用。
● 不指定时表示查询第一页。
● 该字段不允许为空或无效的 ID。
page_reverse 否 Boolean 分页的顺序，true表示从后往前 分页，false表示从前往后分 页，默认为false。
使用说明：
● 必须与limit一起使用。
protocol_port 否 Array 监听器的前端监听端口。
支持多值查询，查询条件格式：
protocol_port=xxx&protocol_p ort=xxx。
protocol 否 Array 监听器的监听协议。
取值：TCP、UDP、HTTP、
HTTPS、
TERMINATED_HTTPS。
说明：TERMINATED_HTTPS为 共享型LB上的监听器独有的协 议。
支持多值查询，查询条件格式：
protocol=xxx&protocol=xxx。 description 否 Array 监听器的描述信息。
支持多值查询，查询条件格式：
description=xxx&description=x xx。
default_tls_co
ntainer_ref 否 Array 监听器的服务器证书ID。 支持 多值查询，查询条件格式：
default_tls_container_ref=xxx&
default_tls_container_ref=xxx
。
参数 是否必选 参数类型 描述 client_ca_tls_c
ontainer_ref 否 Array 监听器的CA证书ID。 支持多值 查询，查询条件格式： on_limit=xxx。
不支持该字段，请勿使用。 ool_id=xxx。
id 否 Array 监听器ID。
支持多值查询，查询条件格式：
id=xxx&id=xxx。
name 否 Array 监听器名称。
支持多值查询，查询条件格式：
name=xxx&name=xxx。 http2_enable 否 Boolean 客户端与监听器之间的HTTPS请
求的HTTP2功能的开启状态。开 启后，可提升客户端与LB间的 访问性能，但LB与后端服务器 间仍采用HTTP1.X协议。 非 HTTPS协议的监听器该字段无 ncer_id=xxx。
参数 是否必选 参数类型 描述 tls_ciphers_po
licy 否 Array 监听器使用的安全策略，仅对
HTTPS协议类型的监听器有效。
取值：tls-1-0-inherit, tls-1-0, tls-1-1, tls-1-2, tls-1-2-strict，
tls-1-2-fs, tls-1-0-with-1-3, tls-1-2-fs-with-1-3, hybrid-policy-1-0。
支持多值查询，查询条件格式：
tls_ciphers_policy=xxx&tls_ciph ers_policy=xxx。
member_addr r_address=xxx。
member_devi er_device_id=xxx。
enterprise_pro
ject_id 否 Array 企业项目ID。
支持多值查询，查询条件格式：
enterprise_project_id=xxx&ent erprise_project_id=xxx。 enable_memb
er_retry 否 Boolean 是否开启后端服务器的重试。取 值：true 开启重试，false 不开 启重试。 返回 HTTP504错误码。
取值：1-300s。
支持多值查询，查询条件格式：
member_timeout=xxx&membe r_timeout=xxx。
参数 是否必选 参数类型 描述
client_timeout 否 Array 等待客户端请求超时时间，包括 两种情况： eout=xxx。
keepalive_tim
● TCP监听器：10-4000s。
● HTTP/HTTPS/
TERMINATED_HTTPS监听 器：0-4000s。
● UDP监听器不支持此字段。
支持多值查询，查询条件格 式：keepalive_timeout=xxx&kee palive_timeout=xxx。 transparent_cl
ient_ip_enable 否 Boolean 是否透传客户端IP地址。开启后 客户端IP地址将透传到后端服务 器。仅作用于共享型LB的 TCP/UDP监听器。取值：true开 启，false不开启。
enhance_l7pol
icy_enable 否 Boolean 是否开启高级转发策略功能。开 启高级转发策略后，支持更灵活 的转发策略和转发规则设置。取 值：true开启，false不开启。
member_insta
nce_id 否 Array 后端云服务器ID。仅用于查询条
件，不作为响应参数字段。
支持多值查询，查询条件格式：
member_instance_id=xxx&me mber_instance_id=xxx。
请求参数
表4-230 请求 Header 参数
参数 是否必选 参数类型 描述
X-Auth-Token 是 String IAM鉴权Token
响应参数
状态码： 200
表4-231 响应 Body 参数
参数 参数类型 描述
request_id String 请求ID。
注：自动生成 。 page_info PageInfo
object 监听器分页信息。
listeners Array of Listener objects
Listener的列表。
表4-232 PageInfo
参数 参数类型 描述
previous_mar
ker String 分页查询结果中第一条记录的ID next_marker String 分页查询结果中最后一条记录的ID。
current_count Integer 当前的记录数。
表4-233 Listener
参数 参数类型 描述
admin_state_
up Boolean 监听器的管理状态。只能设置为true。
不支持该字段，请勿使用。
client_ca_tls_c
ontainer_ref String 监听器使用的CA证书ID。仅客户端证书有效，其 他类型证书无效。
参数 参数类型 描述 connection_li
mit Integer 监听器的最大连接数。取值：-1表示不限制，默 认为-1。
不支持该字段，请勿使用。
created_at String
监听器的创建时间。格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如：2021-07-30T12:03:44Z default_pool_i
d String 监听器的默认后端云服务器组ID。当请求没有匹
配的转发策略时，转发到默认后端云服务器上处 理。
default_tls_co
ntainer_ref String 监听器使用的服务器证书ID。
description String 监听器的描述信息。
http2_enable Boolean 客户端与LB之间的HTTPS请求的HTTP2功能的开 启状态。开启后，可提升客户端与LB间的访问性 能，但LB与后端服务器间仍采用HTTP1.X协议。
其他协议的监听器该字段无效，无论取值如何都 不影响监听器正常运行。
id String 监听器ID。
insert_header
s ListenerInser
tHeaders
loadbalancers Array of LoadBalancer Ref objects
监听器所属的负载均衡器的ID列表。一个监听器 只支持关联到一个LB。
name String 监听器的名称。
project_id String 监听器所在的项目ID。
protocol String 监听器的监听协议。支持TCP、UDP、HTTP、
HTTPS、TERMINATED HTTPS。
protocol_port Integer 监听器的前端监听端口。客户端将请求发送到该 端口中。
最小值：1 最大值：65535
参数 参数类型 描述 sni_container_
refs Array of
strings 监听器使用的SNI证书（带域名的服务器证书）ID 列表。
tags Array of Tag
objects 标签列表。
updated_at String
监听器的更新时间。格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如：2021-07-30T12:03:44Z tls_ciphers_po
licy String 监听器使用的安全策略，仅对HTTPS协议类型的 监听器有效。
取值：tls-1-0-inherit, tls-1-0, tls-1-1, tls-1-2, tls-1-2-strict，tls-1-2-fs, tls-1-0-with-1-3, tls-1-2-fs-with-1-3, hybrid-policy-1-0，默认：
tls-1-0。
使用说明：
● 若同时设置了security_policy_id和
tls_ciphers_policy，则仅security_policy_id生 效。
security_polic
y_id String 自定义安全策略的ID。仅关联LB为独享型时有 效。
若同时设置了security_policy_id和
tls_ciphers_policy，则仅security_policy_id生 效。
enable_memb
er_retry Boolean 是否开启后端服务器的重试。取值：true 开启重 试，false 不开启重试。默认：true。
使用说明：
● 若关联是共享型LB，仅在protocol为HTTP、
TERMINATED_HTTPS时才能传入该字段。
● 若关联是独享型LB，仅在protocol为HTTP、
HTTPS时才能传入该字段。
keepalive_tim
eout Integer 客户端连接空闲超时时间。在超过
keepalive_timeout时长一直没有请求，负载均衡 会暂时中断当前连接，直到一下次请求时重新建 立新的连接。取值：
● 若为TCP监听器，取值范围为（10-4000s）默 认值为300s。
● 若为HTTP/HTTPS/TERMINATED_HTTPS监听 器，取值范围为（0-4000s）默认值为60s。
UDP监听器不支持此字段。
参数 参数类型 描述
client_timeout Integer 等待客户端请求超时时间，包括两种情况：
● 读取整个客户端请求头的超时时长：如果客户 端未在超时时长内发送完整个请求头，则请求 将被中断
● 两个连续body体的数据包到达LB的时间间 隔，超出client_timeout将会断开连接。
取值范围为1-300s，默认值为60s。
使用说明：
● 仅协议为HTTP/HTTPS的监听器支持该字段。
member_time
out Integer 等待后端服务器响应超时时间。请求转发后端服 务器后，在等待超时member_timeout时长没有 响应，负载均衡将终止等待，并返回 HTTP504错 误码。
取值：1-300s，默认为60s。
使用说明：
● 仅支持协议为HTTP/HTTPS的监听器。
ipgroup ListenerIpGro
up object listener对象中的ipgroup信息 transparent_cl
ient_ip_enable Boolean 是否透传客户端IP地址。开启后客户端IP地址将 透传到后端服务器。仅作用于共享型LB的 TCP/UDP监听器。取值：
● 共享型LB的TCP/UDP监听器可设置为true或 false，不传默认为false。
● 共享型LB的HTTP/HTTPS监听器只支持设置为 true，不传默认为true。
● 独享型负载均衡器所有协议的监听器只支持设 置为true，不传默认为true。
使用说明：
● 开启特性后，ELB和后端服务器之间直接使用 真实的IP访问，需要确保已正确设置服务器的 安全组以及访问控制策略。
● 开启特性后，不支持同一台服务器既作为后端 服务器又作为客户端的场景。
● 开启特性后，暂不支持变更后端服务器规格。
参数 参数类型 描述 enhance_l7pol
icy_enable Boolean 是否开启高级转发策略功能。开启高级转发策略 后，支持更灵活的转发策略和转发规则设置。取 值：true开启，false不开启，默认false。 开启后 支持如下场景：
● 转发策略的action字段支持指定为
REDIRECT_TO_URL, FIXED_RESPONSE，即支 持URL重定向和响应固定的内容给客户端。
● 转发策略支持指定priority、
redirect_url_config、fixed_response_config 字段。
● 转发规则rule的type可以指定METHOD, HEADER, QUERY_STRING, SOURCE_IP这几种 取值。
● 转发规则rule的type为HOST_NAME时，转发 规则rule的value支持通配符*。
● 转发规则支持指定conditions字段。
缺省值：false
表4-234 ListenerInsertHeaders
参数 参数类型 描述
X-Forwarded-ELB-IP Boolean X-Forwarded-ELB-IP设为true可以将ELB实例的 eip地址从报文的http头中带到后端云服务器。
缺省值：false
X-Forwarded-Port Boolean X-Forwarded-Port设为true可以将ELB实例的监听 端口从报文的http头中带到后端云服务器。
缺省值：false
X-Forwarded-For-Port Boolean X-Forwarded-For-Port设为true可以将客户端的 源端口从报文的http头中带到后端云服务器。
缺省值：false
X-Forwarded-Host Boolean X-Forwarded-Host设为true可以将客户请求头的 X-Forwarded-Host设置为请求头的Host带到后端 云服务器。
缺省值：true
表4-235 LoadBalancerRef
参数 参数类型 描述
id String 负载均衡器ID。
表4-236 Tag
参数 参数类型 描述
key String 标签键
最小长度：1 最大长度：36 value String 标签值
最小长度：0 最大长度：43
表4-237 ListenerIpGroup
参数 参数类型 描述
ipgroup_id String 监听器关联的访问控制组的id。 创建时必选，更 新时非必选。 指定的ipgroup必须已存在，不能 指定为null，否则与enable_ipgroup冲突。
enable_ipgrou
p Boolean 访问控制组的状态。 True:开启访问控制；
False：关闭访问控制； 开启访问控制的监听器，
允许直接删除。
type String 访问控制组的类型。 white:白名单，只允许指定 ip访问； black:黑名单，不允许指定ip访问；
请求示例
分页查询监听器列表
GET https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners?
limit=2&marker=0r31747a-b139-492f-2749-2df0b1c87193
响应示例
状态码： 200 操作正常返回。
{ "listeners" : [ {
"id" : "0b11747a-b139-492f-9692-2df0b1c87193", "name" : "My listener",
"protocol_port" : 80, "protocol" : "TCP", "ipgroup" : null,
"description" : "My listener update.", "default_tls_container_ref" : null, "admin_state_up" : true, "loadbalancers" : [ {
"id" : "098b2f68-af1c-41a9-8efd-69958722af62"
} ],
"keepalive_timeout" : 300, "client_ca_tls_container_ref" : null,
"project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "sni_container_refs" : [ ],
"connection_limit" : -1, "default_pool_id" : null, "tls_ciphers_policy" : "tls-1-0", "tags" : [ ],
"created_at" : "2019-04-02T00:12:32Z", "updated_at" : "2019-04-02T17:43:46Z", "http2_enable" : true,
"transparent_client_ip_enable" : false, "quic_config" : null
}, {
"id" : "0b455839-3ea7-4bac-ad26-35bf22f96ea4", "name" : "listener-test",
"protocol_port" : 86,
"protocol" : "TERMINATED_HTTPS", "description" : null,
"default_tls_container_ref" : "ad9b123e858d4652b80e89b9941e49a4", "admin_state_up" : true,
"default_tls_container_ref" : "ad9b123e858d4652b80e89b9941e49a4", "admin_state_up" : true,