接口约束
4.10 监听器
4.10.1 创建监听器
功能介绍
创建监听器。
接口约束
1.负载均衡器只有四层规格的，只支持创建TCP，UDP的监听器。
2.负载均衡器只有七层规格的，只支持创建HTTP和HTTPS的监听器。
3.负载均衡器既有四层规格也有七层规格，那么支持创建TCP，UDP，HTTP和HTTPS 的监听器。
调试
您可以在API Explorer中调试该接口。
URI
POST /v3/{project_id}/elb/listeners
表4-215 路径参数
参数 是否必选 参数类型 描述
project_id 是 String 项目ID。
请求参数
表4-216 请求 Header 参数
参数 是否必选 参数类型 描述
X-Auth-Token 是 String IAM鉴权Token。
表4-217 请求 Body 参数
参数 是否必选 参数类型 描述
listener 是 CreateListen erOption object
监听器对象。
表4-218 CreateListenerOption
参数 是否必选 参数类型 描述
admin_state_
up 否 Boolean 监听器的管理状态。固定为
true。
不支持该字段，请勿使用。
default_pool_i
d 否 String 监听器默认的后端云服务器组
ID。当请求没有匹配的转发策略 时，转发到默认后端云服务器上 处理。
最小长度：1 最大长度：36 client_ca_tls_c
ontainer_ref 否 String 监听器使用的CA证书ID。仅客 户端证书有效，其他类型证书无 效。
最小长度：1 最大长度：128 default_tls_co
ntainer_ref 否 String 监听器使用的服务器证书ID。
使用说明：
● 当监听器协议为HTTPS或 QUIC时，该字段必传，且对 应的证书的type必须是server 类型，QUIC监听器仅支持 RSA证书。
最小长度：1 最大长度：128
参数 是否必选 参数类型 描述
description 否 String 监听器的描述信息。
最小长度：0 最大长度：255
http2_enable 否 Boolean 客户端与LB之间的HTTPS请求 的HTTP2功能的开启状态。开启
s 否 ListenerInser
tHeaders
project_id 否 String 监听器所在的项目ID。
最小长度：1 最大长度：32
protocol 是 String 监听器的监听协议。支持TCP、
UDP、HTTP、HTTPS、
TERMINATED_HTTPS和QUIC。
参数 是否必选 参数类型 描述
protocol_port 是 Integer 监听器的监听端口。UDP和 QUIC监听器端口不能是4789，
strings 监听器使用的SNI证书（带域名 的服务器证书）ID列表。
● QUIC监听器仅支持RSA证 书。
tags 否 Array of Tag
objects 标签列表 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。
y_id 否 String 自定义安全策略的ID。仅对
HTTPS协议类型的监听器且关联
参数 是否必选 参数类型 描述 enable_memb
er_retry 否 Boolean 是否开启后端服务器的重试。取 值：true 开启重试，false 不开 启重试。默认：true。
● 若为TCP/UDP监听器，取值 范围为（10-4000s）默认值 为300s。
● 若为HTTP/HTTPS/
TERMINATED_HTTPS/QUIC 监听器，取值范围为
（0-4000s）默认值为60s。
共享型LB的UDP监听器不支持 此字段。
client_timeout 否 Integer 等待客户端请求超时时间，包括 两种情况：
参数 是否必选 参数类型 描述 返回 HTTP504错误码。
取值：1-300s，默认为60s。
使用说明：
● 仅支持协议为HTTP/HTTPS/
QUIC的监听器。
最小值：1 最大值：300 缺省值：60 ipgroup 否 CreateListen
erIpGroupOp tion object
listener对象中的控制组
ient_ip_enable 否 Boolean 是否透传客户端IP地址。开启后 客户端IP地址将透传到后端服务 器。仅作用于共享型LB的 TCP/UDP监听器。取值：
● 共享型LB的TCP/UDP监听器 可设置为true或false，不传 默认为false。
● 共享型LB的HTTP/HTTPS监 听器只支持设置为true，不
参数 是否必选 参数类型 描述 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 字段。
表4-219 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-220 Tag
参数 是否必选 参数类型 描述
key 否 String 标签键
最小长度：1 最大长度：36
value 否 String 标签值
最小长度：0 最大长度：43
表4-221 CreateListenerIpGroupOption
参数 是否必选 参数类型 描述
ipgroup_id 是 String 监听器关联的访问控制组的id。
当关联的ipgroup中的ip_list为 []，且类型为白名单时，表示禁 止所有ip的访问。
当关联的ipgroup中的ip_list为 []，且类型为黑名单时，表示允 许所有ip的访问。
最小长度：1 最大长度：36 enable_ipgrou
p 否 Boolean 访问控制组的状态。取值：
● true：开启访问控制，默认 值。
● false：关闭访问控制。
type 否 String 访问控制组的类型。
● white：白名单，只允许指定 ip访问，默认值。
● black：黑名单，不允许指定 ip访问。
响应参数
状态码： 201
表4-222 响应 Body 参数
参数 参数类型 描述
request_id String 请求ID。
注：自动生成 。 listener Listener
object 监听器对象。
表4-223 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。
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-224 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-225 LoadBalancerRef
参数 参数类型 描述
id String 负载均衡器ID。
表4-226 Tag
参数 参数类型 描述
key String 标签键
最小长度：1 最大长度：36 value String 标签值
最小长度：0
最小长度：0