创建监听器

功能介绍

创建监听器。支持通过该接口创建独享型及共享型LB实例下的监听器。

接口约束

1.负载均衡器只有四层规格的，只支持创建TCP，UDP和TLS的监听器。

2.负载均衡器只有七层规格的，只支持创建HTTP、HTTPS和QUIC的监听器。

3.负载均衡器既有四层规格也有七层规格，那么支持创建TCP、UDP、TLS、HTTP、HTTPS和QUIC的监听器。

4.有且仅有网关型负载均衡器，支持创建IP监听器。

调用方法

请参见如何调用API。

URI

POST /v3/{project_id}/elb/listeners

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	参数解释：项目ID。获取方式请参见获取项目ID。约束限制：不涉及取值范围：长度为32个字符，由小写字母和数字组成。默认取值：不涉及

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：IAM鉴权Token。约束限制：不涉及取值范围：不涉及默认取值：不涉及

表3 请求Body参数
参数	是否必选	参数类型	描述
listener	是	CreateListenerOption object	参数解释：创建监听器请求参数。约束限制：不涉及

表4 CreateListenerOption
参数	是否必选	参数类型	描述
admin_state_up	否	Boolean	参数解释：监听器的管理状态。约束限制：只支持设置为true。取值范围：true 表示监听器正常使用中。默认取值：true
default_pool_id	否	String	参数解释：监听器默认的后端服务器组ID。当请求没有匹配的转发策略时，转发到默认后端服务器组上处理。约束限制：不涉及取值范围：不涉及默认取值：不涉及
client_ca_tls_container_ref	否	String	参数解释：监听器使用的CA证书ID。约束限制：对应证书的type必须是client类型。仅TLS和HTTPS协议监听器支持该字段。开启双向认证需要同时传入client_ca_tls_container_ref和default_tls_container_ref。取值范围：不涉及默认取值：不涉及
default_tls_container_ref	否	String	参数解释：监听器使用的服务器证书ID。约束限制：对应证书的type必须是server类型。当监听器协议为HTTPS、TLS或QUIC时，该字段必传。开启双向认证需要同时传入client_ca_tls_container_ref和default_tls_container_ref。开启单向认证时，只需要传入default_tls_container_ref。取值范围：不涉及默认取值：不涉及
description	否	String	参数解释：监听器的描述信息。约束限制：不涉及取值范围：不涉及默认取值：不涉及
http2_enable	否	Boolean	参数解释：客户端与LB之间的HTTPS请求的HTTP2功能的开启状态。开启后，可提升客户端与LB间的访问性能，但LB与后端服务器间仍采用HTTP1.X协议。约束限制：仅HTTPS协议监听器有效。 QUIC监听器不能设置该字段，固定返回为true。其他协议的监听器可设置该字段但无效，无论取值如何都不影响监听器正常运行。取值范围： true：开启 false：不开启默认取值：false
insert_headers	否	ListenerInsertHeaders object	参数解释：附加的HTTP头字段，ELB会将特定的HTTP头字段写入到请求头中，并随报文传递到后端服务器。例如可通过X-Forwarded-ELB-IP开关，将负载均衡器的弹性公网IP传到后端服务器。约束限制：仅HTTP/HTTPS/QUIC协议支持该字段。
loadbalancer_id	是	String	参数解释：监听器所属的负载均衡器的ID。约束限制：一个监听器只支持关联到一个负载均衡器。取值范围：不涉及默认取值：不涉及
name	否	String	参数解释：监听器的名称。约束限制：若名称为空，则在控制台的监听器列表无法选择并查看监听器详情。取值范围：长度为0-255个字符。默认取值：不涉及
project_id	否	String	参数解释：项目ID。获取方式请参见获取项目ID。约束限制：不涉及取值范围：长度为32个字符，由小写字母和数字组成。默认取值：不涉及说明：该字段实际无效，最终使用url中的project_id。
protocol	是	String	参数解释：监听器的监听协议。默认取值：不涉及
protocol_port	否	Integer	参数解释：监听器的监听端口。约束限制： QUIC和UDP监听器端口不能重复。 TCP、HTTP、HTTPS监听器之间端口不能重复。传0时表示开启监听端口范围的能力，此时全端口监听port_ranges为必填字段。取值范围：0-65535 默认取值：不涉及
sni_container_refs	否	Array of strings	参数解释：监听器使用的SNI证书（带域名的服务器证书）ID列表。约束限制： QUIC监听器仅支持RSA证书。列表对应的所有SNI证书的域名不允许存在重复。列表对应的所有SNI证书的域名总数不超过200。取值范围：0-50个。默认取值：不涉及
sni_match_algo	否	String	参数解释：监听器使用的SNI证书泛域名匹配方式。约束限制：不涉及取值范围： longest_suffix 表示最长尾缀匹配。 wildcard 表示标准域名分级匹配。默认取值：wildcard。
tags	否	Array of Tag objects	参数解释：资源标签。约束限制：不涉及
tls_ciphers_policy	否	String	参数解释：监听器使用的安全策略。默认取值：不涉及
security_policy_id	否	String	参数解释：自定义安全策略的ID。取值范围：不涉及默认取值：不涉及
enable_member_retry	否	Boolean	参数解释：是否开启后端服务器的重试。取值范围：true 开启重试，false 不开启重试。默认取值：true
keepalive_timeout	否	Integer	参数解释：客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求，负载均衡会暂时中断当前连接，直到下一次请求时重新建立新的连接。约束限制：共享型实例的UDP监听器不支持此字段。取值范围： TCP、UDP和IP监听器：10-4000s，默认值为300s。 HTTP、HTTPS和TERMINATED_HTTPS监听器：0-4000s，默认值为60s。默认取值：不涉及
client_timeout	否	Integer	参数解释：等待客户端请求超时时间，包括两种情况：读取整个客户端请求头的超时时长：如果客户端未在超时时长内发送完整个请求头，则请求将被中断两个连续body体的数据包到达LB的时间间隔，超出client_timeout将会断开连接。约束限制：仅协议为HTTP/HTTPS的监听器支持该字段。取值范围： 1-300s 默认取值：60s
member_timeout	否	Integer	参数解释：等待后端服务器响应超时时间。请求转发后端服务器后，在等待超时member_timeout时长没有响应，负载均衡将终止等待，并返回HTTP504错误码。约束限制：仅支持协议为HTTP/HTTPS的监听器。取值范围：1-300s 默认取值：60s
ipgroup	否	CreateListenerIpGroupOption object	参数解释：监听器对象中的控制组（ipgroup）信息，可以不传或传null或{}，表示监听器不绑定访问控制组。若需要绑定访问控制组，则ipgroup_id是必须的。约束限制：不涉及
transparent_client_ip_enable	否	Boolean	参数解释：是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。默认取值：不涉及
proxy_protocol_enable	否	Boolean	参数解释：是否开启proxy_protocol。约束限制：仅TLS监听器可指定，其他协议的监听器该字段不生效，proxy_protocol不开启。取值范围：不涉及默认取值：不涉及
enhance_l7policy_enable	否	Boolean	参数解释：是否开启高级转发策略功能。开启高级转发策略后，支持更灵活的转发策略和转发规则设置。开启后支持如下场景：转发策略的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字段。约束限制：开启后不支持关闭。开启高级转发策略后，监听器关联的转发策略的匹配优先级由转发策略的priority字段来决定，不再自动排序。具体说明详见转发策略的priority字段的说明。取值范围：true开启，false不开启。默认取值*：false。
quic_config	否	CreateListenerQuicConfigOption object	参数解释：当前监听器关联的QUIC监听器配置信息。约束限制：仅protocol为HTTPS时有效。对于TCP/UDP/HTTP/QUIC监听器，若该字段非空则报错。说明：客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。如果服务端监听器开启了升级QUIC，那么就会在响应头中加入服务端支持的QUIC端口和版本信息。客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求，若QUIC请求成功，则后续继续使用QUIC交互。
cps	否	Integer	参数解释：监听器新建限速。约束限制：当该限速值大于LB的限速值时，以LB的限速值生效取值范围：0-1000000 默认取值：0，表示不限速。
connection	否	Integer	参数解释：监听器并发限速约束限制：当该限速值大于LB的限速值时，以LB的限速值生效取值范围：0-1000000 默认取值：0，表示不限速。
nat64_enable	否	Boolean	参数解释：监听器地址转换能力开关，可以实现客户端通过访问LB的IPv4或者IPv6地址，来访问IPv4后端和IPv6后端。约束限制：仅对于TCP、UDP协议类型的监听器生效，与transparent_client_ip_enable，获取客户端ip功能开关互斥，开启地址转换同时需要保证获取客户端ip功能关闭。取值范围： true：开启地址转换功能 false：关闭地址转换功能默认取值：false

表5 ListenerInsertHeaders
参数	是否必选	参数类型	描述
X-Forwarded-ELB-IP	否	Boolean	参数解释：X-Forwarded-ELB-IP设为true可以将ELB实例的eip地址从报文的http头中带到后端服务器。
X-Forwarded-Port	否	Boolean	参数解释：X-Forwarded-Port设为true可以将ELB实例的监听端口从报文的http头中带到后端服务器。
X-Forwarded-For-Port	否	Boolean	参数解释：X-Forwarded-For-Port设为true可以将客户端的源端口从报文的http头中带到后端服务器。
X-Forwarded-Host	否	Boolean	参数解释：X-Forwarded-Host设为true可以将客户请求头的X-Forwarded-Host设置为请求头的Host带到后端服务器。
X-Forwarded-Proto	否	Boolean	参数解释：X-Forwarded-Proto设为true可以将负载均衡器实例的监听协议通过报文的http头带到后端服务器。
X-Real-IP	否	Boolean	参数解释：X-Real-IP设为true可以将客户端的IP通过报文的http头带到后端服务器。
X-Forwarded-ELB-ID	否	Boolean	参数解释：X-Forwarded-ELB-ID设为true可以将负载均衡器实例的ID通过报文的http头带到后端服务器。
X-Forwarded-TLS-Certificate-ID	否	Boolean	参数解释：X-Forwarded-TLS-Certificate-ID设为true可以将负载均衡器实例的证书ID通过报文的http头带到后端服务器。
X-Forwarded-TLS-Protocol	否	Boolean	参数解释：X-Forwarded-TLS-Protocol设为true可以将负载均衡器实例的算法协议通过报文的http头带到后端服务器。
X-Forwarded-TLS-Cipher	否	Boolean	参数解释：X-Forwarded-TLS-Cipher设为true可以将负载均衡器实例的算法套件通过报文的http头带到后端服务器。
X-Forwarded-TLS-Protocol-alias	否	String	参数解释：自定义X-Forwarded-TLS-Protocol头字段名称。约束限制：只有当 X-Forwarded-TLS-Protocol 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-TLS-Cipher-alias	否	String	参数解释：自定义X-Forwarded-TLS-Cipher头字段名称。约束限制：只有当 X-Forwarded-TLS-Cipher 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-For-Processing-Mode	否	String	参数解释：处理X-Forwarded-For头字段的模式：配置 append，将请求发送至后端服务之前把最后一跳 IP 加入X-Forwarded-For头字段；配置 remove，请求发送至后端服务之前删除X-Forwarded-For标头，无论请求是否携带X-Forwarded-For头字段；配置preserve，保留请求中已有的X-Forwarded-For标头；约束限制：仅HTTP、HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段；取值范围：append、remove、preserve 默认取值：append
X-Forwarded-Clientcert-subjectdn-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-subjectdn头字段获取访问负载均衡实例客户端证书的所有者信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-subjectdn-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-subjectdn头字段名称。约束限制：只有当 X-Forwarded-Clientcert-subjectdn-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-issuerdn-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-issuerdn头字段获取访问负载均衡实例客户端证书的发行者信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-issuerdn-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-issuerdn头字段名称。约束限制：只有当 X-Forwarded-Clientcert-issuerdn-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-fingerprint-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-fingerprint头字段获取访问负载均衡实例客户端证书的指纹取值。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-fingerprint-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-fingerprint头字段名称。约束限制：只有当 X-Forwarded-Clientcert-fingerprint-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-clientverify-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-clientverify头字段获取对访问负载均衡实例客户端证书的校验结果。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-clientverify-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-clientverify头字段名称。约束限制：只有当 X-Forwarded-Clientcert-clientverify-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-serialnumber-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-serialnumber 头字段获取客户端证书的序列号信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-serialnumber-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-serialnumber头字段名称。约束限制：只有当X-Forwarded-Clientcert-serialnumber-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert 头字段获取客户端证书的内容。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-alias	否	String	参数解释：自定义X-Forwarded-Clientcert头字段名称。约束限制：只有当X-Forwarded-Clientcert-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC、TLS协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-ciphers-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-ciphers 头字段获取客户端支持的TLS加密套件。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-ciphers-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-ciphers头字段名称。约束限制：只有当X-Forwarded-Clientcert-ciphers-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-end-enable	否	Boolean	参数解释：是否通过X-Forwarded-Clientcert-end 头字段获取客户端证书的结束日期。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-end-alias	否	String	参数解释：自定义X-Forwarded-Clientcert-end头字段名称。约束限制：只有当X-Forwarded-Clientcert-end-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC、TLS协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Alpn-Protocol-enable	否	Boolean	参数解释：是否通过X-Forwarded-Tls-Alpn-Protocol 头字段获取客户端和服务器之间ALPN（Application-Layer Protocol Negotiation）协商的应用层协议。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Alpn-Protocol-alias	否	String	参数解释：自定义X-Forwarded-Tls-Alpn-Protocol头字段名称。约束限制：只有当X-Forwarded-Tls-Alpn-Protocol-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Sni-enable	否	Boolean	参数解释：是否通过X-Forwarded-Tls-Sni 头字段获取客户端访问的sni证书的域名。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Sni-alias	否	String	参数解释：自定义X-Forwarded-Tls-Sni头字段名称。约束限制：只有当X-Forwarded-Tls-Sni-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Ja3-enable	否	Boolean	参数解释：是否通过X-Forwarded-Tls-Ja3头字段获取访问负载均衡实例客户端的ja3指纹。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Ja3-alias	否	String	参数解释：自定义X-Forwarded-Tls-Ja3头字段名称。约束限制：只有当X-Forwarded-Tls-Ja3-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Ja4-enable	否	Boolean	参数解释：是否通过X-Forwarded-Tls-Ja4头字段获取访问负载均衡实例客户端的ja4指纹。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Ja4-alias	否	String	参数解释：自定义X-Forwarded-Tls-Ja4头字段名称。约束限制：只有当X-Forwarded-Tls-Ja4-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无

表6 Tag
参数	是否必选	参数类型	描述
key	否	String	参数解释：标签键。取值范围：不涉及
value	否	String	参数解释：标签值。取值范围：不涉及

表7 CreateListenerIpGroupOption
参数	是否必选	参数类型	描述
ipgroup_id	是	String	参数解释：监听器关联的访问控制组的ID。关联多个IP地址组时ID使用逗号分隔。约束限制：当关联的ipgroup中的ip_list为[]，且类型为白名单时，表示禁止所有ip的访问。当关联的ipgroup中的ip_list为[]，且类型为黑名单时，表示允许所有ip的访问。取值范围：不涉及默认取值：不涉及
enable_ipgroup	否	Boolean	参数解释：访问控制组的状态。约束限制：不涉及取值范围： true：开启访问控制，默认值。 false：关闭访问控制。默认取值：不涉及
type	否	String	参数解释：访问控制组的类型。约束限制：不涉及取值范围： white：白名单，只允许指定ip访问。 black：黑名单，不允许指定ip访问。默认取值：white

表8 CreateListenerQuicConfigOption
参数	是否必选	参数类型	描述
quic_listener_id	是	String	参数解释：监听器关联的QUIC监听器ID。约束限制：指定的listener id必须已存在，且协议类型为QUIC，不能指定为null，否则与enable_quic_upgrade冲突。取值范围：不涉及默认取值：不涉及
enable_quic_upgrade	否	Boolean	参数解释：QUIC升级的开启状态。开启HTTPS监听器升级QUIC监听器能力。约束限制：不涉及取值范围： true:开启QUIC升级。 false：关闭QUIC升级。默认取值：false

响应参数

状态码：201

表9 响应Body参数
参数	参数类型	描述
request_id	String	参数解释：请求ID。取值范围：由数字、小写字母和中划线（-）组成的字符串，自动生成。
listener	Listener object	参数解释：监听器对象。

**表10** Listener
参数	参数类型	描述
admin_state_up	Boolean	参数解释：监听器的管理状态。取值范围：true
client_ca_tls_container_ref	String	参数解释：监听器使用的CA证书ID。当且仅当type=client时，才会使用该字段对应的证书。取值范围：不涉及
connection_limit	Integer	参数解释：监听器的最大连接数。取值范围：大于等于-1的整数。
created_at	String	参数解释：监听器的创建时间。取值范围：不涉及格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如：2021-07-30T12:03:44Z
default_pool_id	String	参数解释：监听器的默认后端服务器组ID。当请求没有匹配的转发策略时，转发到默认后端服务器组上处理。取值范围：不涉及
default_tls_container_ref	String	参数解释：监听器使用的服务器证书ID。取值范围：不涉及
description	String	参数解释：监听器的描述信息。取值范围：不涉及
http2_enable	Boolean	参数解释：客户端与LB之间的HTTPS请求的HTTP2功能的开启状态。开启后，可提升客户端与LB间的访问性能，但LB与后端服务器间仍采用HTTP1.X协议。取值范围：不涉及
id	String	参数解释：监听器ID。取值范围：不涉及
insert_headers	ListenerInsertHeaders object	参数解释：附加的HTTP头字段，ELB会将特定的HTTP头字段写入到请求头中，并随报文传递到后端服务器。例如可通过X-Forwarded-ELB-IP开关，将负载均衡器的弹性公网IP传到后端服务器。
loadbalancers	Array of LoadBalancerRef objects	参数解释：监听器所属的负载均衡器的ID列表。实际上一个监听器只支持关联到一个LB。
name	String	参数解释：监听器的名称。若名称为空，则在控制台的监听器列表无法选择并查看监听器详情。取值范围：不涉及
project_id	String	参数解释：监听器所在的项目ID。取值范围：不涉及
enterprise_project_id	String	参数解释：企业项目ID。取值范围：不涉及
protocol	String	参数解释：监听器的监听协议。
protocol_port	Integer	参数解释：监听器的监听端口。取值范围：不涉及
sni_container_refs	Array of strings	参数解释：监听器使用的SNI证书（带域名的服务器证书）ID列表。取值范围：不涉及
sni_match_algo	String	参数解释：监听器使用的SNI证书泛域名匹配方式。取值范围：longest_suffix表示最长尾缀匹配；wildcard表示标准域名分级匹配。
tags	Array of Tag objects	参数解释：标签列表。
updated_at	String	参数解释：监听器的更新时间。取值范围：格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如：2021-07-30T12:03:44Z
tls_ciphers_policy	String	参数解释：监听器使用的安全策略。
security_policy_id	String	参数解释：自定义安全策略的ID。取值范围：不涉及
enable_member_retry	Boolean	参数解释：是否开启后端服务器的重试。取值范围：true 开启重试，false 不开启重试。
keepalive_timeout	Integer	参数解释：客户端连接空闲超时时间。在超过keepalive_timeout时长一直没有请求，负载均衡会暂时中断当前连接，直到下一次请求时重新建立新的连接。取值范围： TCP、UDP和IP监听器：10-4000s，默认值为300s。 HTTP、HTTPS和TERMINATED_HTTPS监听器：0-4000s，默认值为60s。
client_timeout	Integer	参数解释：等待客户端请求超时时间，包括两种情况：读取整个客户端请求头的超时时长：如果客户端未在超时时长内发送完整个请求头，则请求将被中断两个连续body体的数据包到达LB的时间间隔，超出client_timeout将会断开连接。取值范围：1-300，单位：秒。
member_timeout	Integer	参数解释：等待后端服务器响应超时时间。请求转发后端服务器后，在等待超时member_timeout时长没有响应，负载均衡将终止等待，并返回HTTP504错误码。取值范围：1-300，单位：秒。
ipgroup	ListenerIpGroup object	参数解释：listener对象中的ipgroup信息。
transparent_client_ip_enable	Boolean	参数解释：是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。取值范围：共享型LB的TCP/UDP监听器可设置为true或false，不传默认为false。共享型LB的HTTP/HTTPS监听器只支持设置为true，不传默认为true。独享型负载均衡器所有协议的监听器只支持设置为true，不传默认为true。
proxy_protocol_enable	Boolean	参数解释：是否开启proxy_protocol。仅TLS监听器可指定，其他协议的监听器该字段不生效，proxy_protocol不开启。取值范围：true 开启，false 不开启。
enhance_l7policy_enable	Boolean	参数解释：是否开启高级转发策略功能。开启高级转发策略后，支持更灵活的转发策略和转发规则设置。开启后支持如下场景：转发策略的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字段。取值范围*：true开启，false不开启。
quic_config	ListenerQuicConfig object	参数解释：当前监听器关联的QUIC监听器配置信息。
gzip_enable	Boolean	参数解释：ELB是否开启gzip压缩。取值范围：true开启，false不开启。
port_ranges	Array of PortRange objects	参数解释：全端口监听，指定端口监听范围（闭区间)。
cps	Integer	参数解释：监听器新建限速。当该限速值大于LB的限速值时，以LB的限速值生效。取值范围：0-1000000
connection	Integer	参数解释：监听器并发限速。当该限速值大于LB的限速值时，以LB的限速值生效。取值范围：0-1000000
nat64_enable	Boolean	参数解释：监听器地址转换能力开关，可以实现客户端通过访问LB的IPv4或者IPv6地址，来访问IPv4后端和IPv6后端。取值范围： true：开启地址转换功能。 false：关闭地址转换功能。

**表11** ListenerInsertHeaders
参数	参数类型	描述
X-Forwarded-ELB-IP	Boolean	参数解释：X-Forwarded-ELB-IP设为true可以将ELB实例的eip地址从报文的http头中带到后端服务器。
X-Forwarded-Port	Boolean	参数解释：X-Forwarded-Port设为true可以将ELB实例的监听端口从报文的http头中带到后端服务器。
X-Forwarded-For-Port	Boolean	参数解释：X-Forwarded-For-Port设为true可以将客户端的源端口从报文的http头中带到后端服务器。
X-Forwarded-Host	Boolean	参数解释：X-Forwarded-Host设为true可以将客户请求头的X-Forwarded-Host设置为请求头的Host带到后端服务器。
X-Forwarded-Proto	Boolean	参数解释：X-Forwarded-Proto设为true可以将负载均衡器实例的监听协议通过报文的http头带到后端服务器。
X-Real-IP	Boolean	参数解释：X-Real-IP设为true可以将客户端的IP通过报文的http头带到后端服务器。
X-Forwarded-ELB-ID	Boolean	参数解释：X-Forwarded-ELB-ID设为true可以将负载均衡器实例的ID通过报文的http头带到后端服务器。
X-Forwarded-TLS-Certificate-ID	Boolean	参数解释：X-Forwarded-TLS-Certificate-ID设为true可以将负载均衡器实例的证书ID通过报文的http头带到后端服务器。
X-Forwarded-TLS-Protocol	Boolean	参数解释：X-Forwarded-TLS-Protocol设为true可以将负载均衡器实例的算法协议通过报文的http头带到后端服务器。
X-Forwarded-TLS-Cipher	Boolean	参数解释：X-Forwarded-TLS-Cipher设为true可以将负载均衡器实例的算法套件通过报文的http头带到后端服务器。
X-Forwarded-TLS-Protocol-alias	String	参数解释：自定义X-Forwarded-TLS-Protocol头字段名称。约束限制：只有当 X-Forwarded-TLS-Protocol 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-TLS-Cipher-alias	String	参数解释：自定义X-Forwarded-TLS-Cipher头字段名称。约束限制：只有当 X-Forwarded-TLS-Cipher 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-For-Processing-Mode	String	参数解释：处理X-Forwarded-For头字段的模式：配置 append，将请求发送至后端服务之前把最后一跳 IP 加入X-Forwarded-For头字段；配置 remove，请求发送至后端服务之前删除X-Forwarded-For标头，无论请求是否携带X-Forwarded-For头字段；配置preserve，保留请求中已有的X-Forwarded-For标头；约束限制：仅HTTP、HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段；取值范围：append、remove、preserve 默认取值：append
X-Forwarded-Clientcert-subjectdn-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-subjectdn头字段获取访问负载均衡实例客户端证书的所有者信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-subjectdn-alias	String	参数解释：自定义X-Forwarded-Clientcert-subjectdn头字段名称。约束限制：只有当 X-Forwarded-Clientcert-subjectdn-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-issuerdn-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-issuerdn头字段获取访问负载均衡实例客户端证书的发行者信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-issuerdn-alias	String	参数解释：自定义X-Forwarded-Clientcert-issuerdn头字段名称。约束限制：只有当 X-Forwarded-Clientcert-issuerdn-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-fingerprint-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-fingerprint头字段获取访问负载均衡实例客户端证书的指纹取值。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-fingerprint-alias	String	参数解释：自定义X-Forwarded-Clientcert-fingerprint头字段名称。约束限制：只有当 X-Forwarded-Clientcert-fingerprint-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-clientverify-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-clientverify头字段获取对访问负载均衡实例客户端证书的校验结果。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-clientverify-alias	String	参数解释：自定义X-Forwarded-Clientcert-clientverify头字段名称。约束限制：只有当 X-Forwarded-Clientcert-clientverify-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-serialnumber-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-serialnumber 头字段获取客户端证书的序列号信息。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-serialnumber-alias	String	参数解释：自定义X-Forwarded-Clientcert-serialnumber头字段名称。约束限制：只有当X-Forwarded-Clientcert-serialnumber-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert 头字段获取客户端证书的内容。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-alias	String	参数解释：自定义X-Forwarded-Clientcert头字段名称。约束限制：只有当X-Forwarded-Clientcert-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC、TLS协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-ciphers-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-ciphers 头字段获取客户端支持的TLS加密套件。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-ciphers-alias	String	参数解释：自定义X-Forwarded-Clientcert-ciphers头字段名称。约束限制：只有当X-Forwarded-Clientcert-ciphers-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Clientcert-end-enable	Boolean	参数解释：是否通过X-Forwarded-Clientcert-end 头字段获取客户端证书的结束日期。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Clientcert-end-alias	String	参数解释：自定义X-Forwarded-Clientcert-end头字段名称。约束限制：只有当X-Forwarded-Clientcert-end-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC、TLS协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Alpn-Protocol-enable	Boolean	参数解释：是否通过X-Forwarded-Tls-Alpn-Protocol 头字段获取客户端和服务器之间ALPN（Application-Layer Protocol Negotiation）协商的应用层协议。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Alpn-Protocol-alias	String	参数解释：自定义X-Forwarded-Tls-Alpn-Protocol头字段名称。约束限制：只有当X-Forwarded-Tls-Alpn-Protocol-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Sni-enable	Boolean	参数解释：是否通过X-Forwarded-Tls-Sni 头字段获取客户端访问的sni证书的域名。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Sni-alias	String	参数解释：自定义X-Forwarded-Tls-Sni头字段名称。约束限制：只有当X-Forwarded-Tls-Sni-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Ja3-enable	Boolean	参数解释：是否通过X-Forwarded-Tls-Ja3头字段获取访问负载均衡实例客户端的ja3指纹。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Ja3-alias	String	参数解释：自定义X-Forwarded-Tls-Ja3头字段名称。约束限制：只有当X-Forwarded-Tls-Ja3-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无
X-Forwarded-Tls-Ja4-enable	Boolean	参数解释：是否通过X-Forwarded-Tls-Ja4头字段获取访问负载均衡实例客户端的ja4指纹。约束限制：仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段。取值范围：true、false 默认取值：false
X-Forwarded-Tls-Ja4-alias	String	参数解释：自定义X-Forwarded-Tls-Ja4头字段名称。约束限制：只有当X-Forwarded-Tls-Ja4-enable 的值为 true 时，此值才会生效。仅HTTPS、TERMINATED_HTTPS、QUIC协议的监听器支持该字段取值范围：1~40 个字符。支持字母 a~z、短划线（-）、下划线（_）和数字。默认取值：无

**表12** LoadBalancerRef
参数	参数类型	描述
id	String	参数解释：负载均衡器ID。取值范围：不涉及

**表13** Tag
参数	参数类型	描述
key	String	参数解释：标签键。取值范围：不涉及
value	String	参数解释：标签值。取值范围：不涉及

**表14** ListenerIpGroup
参数	参数类型	描述
ipgroup_id	String	参数解释：监听器关联的访问控制组的ID。关联多个IP地址组时ID使用逗号分隔。取值范围：不涉及
enable_ipgroup	Boolean	参数解释：访问控制组的状态。开启访问控制的监听器，允许直接删除。取值范围： true:开启访问控制。 false：关闭访问控制。
type	String	参数解释：访问控制组的类型。取值范围： white:白名单，只允许指定ip访问。 black:黑名单，不允许指定ip访问。

**表15** ListenerQuicConfig
参数	参数类型	描述
quic_listener_id	String	参数解释：监听器关联的QUIC监听器ID。取值范围：不涉及
enable_quic_upgrade	Boolean	参数解释：QUIC升级的开启状态。开启HTTPS监听器升级QUIC监听器能力。取值范围： true:开启QUIC升级。 false：关闭QUIC升级。

**表16** PortRange
参数	参数类型	描述
start_port	Integer	参数解释：起始端口。约束限制：不涉及取值范围：1-65535 默认取值：不涉及
end_port	Integer	参数解释：结束端口。约束限制：大于等于起始端口。取值范围：1-65535 默认取值：不涉及

请求示例

示例1：创建protocol为TCP的监听器。

POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners

{
  "listener" : {
    "protocol_port" : 80,
    "protocol" : "TCP",
    "loadbalancer_id" : "098b2f68-af1c-41a9-8efd-69958722af62",
    "name" : "My listener",
    "admin_state_up" : true,
    "insert_headers" : {
      "X-Forwarded-ELB-IP" : true
    }
  }
}

示例2：创建protocol为HTTPS的监听器。

POST https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners

{
  "listener" : {
    "protocol_port" : 90,
    "protocol" : "HTTPS",
    "loadbalancer_id" : "098b2f68-af1c-41a9-8efd-69958722af62",
    "name" : "My listener",
    "admin_state_up" : true,
    "ipgroup" : {
      "ipgroup_id" : "0416b6f1-877f-4a51-987e-978b3f083542",
      "type" : "black"
    },
    "security_policy_id" : "8722e0e0-9cc9-4490-9660-8c9a5732fbb0",
    "default_tls_container_ref" : "233a325e5e3e4ce8beeb320aa714cc12"
  }
}

响应示例

状态码：201

POST操作正常返回。

{
  "listener" : {
    "id" : "0b11747a-b139-492f-9692-2df0b1c87193",
    "name" : "My listener",
    "protocol_port" : 80,
    "protocol" : "TCP",
    "description" : null,
    "default_tls_container_ref" : null,
    "admin_state_up" : true,
    "loadbalancers" : [ {
      "id" : "098b2f68-af1c-41a9-8efd-69958722af62"
    } ],
    "client_ca_tls_container_ref" : null,
    "project_id" : "99a3fff0d03c428eac3678da6a7d0f24",
    "sni_container_refs" : [ ],
    "connection_limit" : -1,
    "member_timeout" : null,
    "client_timeout" : null,
    "keepalive_timeout" : null,
    "default_pool_id" : null,
    "ipgroup" : null,
    "tls_ciphers_policy" : "tls-1-2",
    "tags" : [ ],
    "created_at" : "2019-04-02T00:12:32Z",
    "updated_at" : "2019-04-02T00:12:32Z",
    "http2_enable" : false,
    "enable_member_retry" : true,
    "insert_headers" : {
      "X-Forwarded-ELB-IP" : true
    },
    "transparent_client_ip_enable" : false,
    "nat64_enable" : false
  },
  "request_id" : "f4c4aca8-df16-42e8-8836-33e4b8e9aa8e"
}

状态码

状态码	描述
201	POST操作正常返回。

错误码

请参见错误码。

父主题：监听器

上一篇：监听器

下一篇：查询监听器列表

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试