创建监听器_弹性负载均衡 ELB

功能介绍

创建监听器。

接口约束

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

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

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

调用方法

请参见如何调用API。

URI

POST /v3/{project_id}/elb/listeners

表1 路径参数
参数	是否必选	参数类型	描述
project_id	是	String	项目ID。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	IAM鉴权Token。

表3 请求Body参数
参数	是否必选	参数类型	描述
listener	是	CreateListenerOption object	监听器对象。

表4 CreateListenerOption
参数	是否必选	参数类型	描述
admin_state_up	否	Boolean	监听器的管理状态。固定为true。不支持该字段，请勿使用。
default_pool_id	否	String	监听器默认的后端云服务器组ID。当请求没有匹配的转发策略时，转发到默认后端云服务器上处理。最小长度：1 最大长度：36
client_ca_tls_container_ref	否	String	监听器使用的CA证书ID。当且仅当type=client时，才会使用该字段对应的证书。监听器协议为QUIC时不支持该字段。最小长度：1 最大长度：128
default_tls_container_ref	否	String	监听器使用的服务器证书ID。使用说明：当监听器协议为HTTPS时，该字段必传，且对应的证书的type必须是server类型。最小长度：1 最大长度：128
description	否	String	监听器的描述信息。最小长度：0 最大长度：255
http2_enable	否	Boolean	客户端与LB之间的HTTPS请求的HTTP2功能的开启状态。开启后，可提升客户端与LB间的访问性能，但LB与后端服务器间仍采用HTTP1.X协议。使用说明：仅HTTPS协议监听器有效。 QUIC监听器不能设置该字段，固定返回为true。其他协议的监听器可设置该字段但无效，无论取值如何都不影响监听器正常运行。
insert_headers	否	ListenerInsertHeaders object	可选的HTTP头插入，可以将从负载均衡器到后端云服务器的路径中需要被后端云服务器用到的信息写入HTTP中，随报文传递到后端云服务器使。例如可通过X-Forwarded-ELB-IP开关，将负载均衡器的弹性公网IP传到后端云服务器。
loadbalancer_id	是	String	监听器所属的负载均衡器的ID列表。使用说明：一个监听器只支持关联到一个LB。最小长度：1 最大长度：36
name	否	String	监听器的名称。注意：若名称为空，则在控制台的监听器列表无法选择并查看监听器详情。最小长度：0 最大长度：255
project_id	否	String	监听器所在的项目ID。最小长度：1 最大长度：32
protocol	是	String	监听器的监听协议。取值：TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TCPSSL。使用说明：共享型LB上的HTTPS监听器只支持设置为TERMINATED_HTTPS。传入HTTPS将会自动转为TERMINATED_HTTPS。独享型LB上的HTTPS监听器只支持设置为HTTPS，传入TERMINATED_HTTPS将会自动转为HTTPS。 required: false
protocol_port	否	Integer	监听器的监听端口。QUIC监听器端口不能是4789，且不能和UDP监听器端口重复。传0时表示开启监听端口范围的能力，此时port_ranges为必填字段。最小值：0 最大值：65535
sni_container_refs	否	Array of strings	监听器使用的SNI证书（带域名的服务器证书）ID列表。使用说明：列表对应的所有SNI证书的域名不允许存在重复。列表对应的所有SNI证书的域名总数不超过50。 QUIC监听器仅支持RSA证书。数组长度：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。最小长度：1 最大长度：36
enable_member_retry	否	Boolean	是否开启后端服务器的重试。取值：true 开启重试，false 不开启重试。默认：true。使用说明：若关联是共享型LB，仅在protocol为HTTP、TERMINATED_HTTPS时才能传入该字段。若关联是独享型LB，仅在protocol为HTTP、HTTPS和QUIC时才能传入该字段。
keepalive_timeout	否	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的监听器支持该字段。最小值：1 最大值：300 缺省值：60
member_timeout	否	Integer	等待后端服务器响应超时时间。请求转发后端服务器后，在等待超时member_timeout时长没有响应，负载均衡将终止等待，并返回 HTTP504错误码。取值：1-300s，默认为60s。使用说明：仅支持协议为HTTP/HTTPS的监听器。最小值：1 最大值：300 缺省值：60
ipgroup	否	CreateListenerIpGroupOption object	监听器对象中的控制组（ipgroup）信息，可以不传或传null或{}，表示监听器不绑定访问控制组。若需要绑定访问控制组，则ipgroup_id是必须的。
transparent_client_ip_enable	否	Boolean	是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。仅作用于共享型LB的TCP/UDP监听器。取值：共享型LB的TCP/UDP监听器可设置为true或false，不传默认为false。共享型LB的HTTP/HTTPS监听器只支持设置为true，不传默认为true。独享型负载均衡器所有协议的监听器只支持设置为true，不传默认为true。使用说明：开启特性后，ELB和后端服务器之间直接使用真实的IP访问，需要确保已正确设置服务器的安全组以及访问控制策略。开启特性后，不支持同一台服务器既作为后端服务器又作为客户端的场景。开启特性后，不支持变更后端服务器规格。
proxy_protocol_enable	否	Boolean	是否开启proxy_protocol。仅tcpssl监听器可指定，其他协议的监听器该字段不生效，proxy_protocol不开启。
enhance_l7policy_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字段。说明：开启后不支持关闭
quic_config	否	CreateListenerQuicConfigOption object	当前监听器关联的QUIC监听器配置信息，仅protocol为HTTPS时有效。对于TCP/UDP/HTTP/QUIC监听器，若该字段非空则报错。说明：客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。如果服务端监听器开启了升级QUIC，那么就会在响应头中加入服务端支持的QUIC端口和版本信息。客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求，若QUIC请求成功，则后续继续使用QUIC交互。

表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头带到后端云服务器。

表6 Tag
参数	是否必选	参数类型	描述
key	否	String	标签键最小长度：1 最大长度：36
value	否	String	标签值最小长度：0 最大长度：43

表7 CreateListenerIpGroupOption
参数	是否必选	参数类型	描述
ipgroup_id	是	String	监听器关联的访问控制组的id。当关联的ipgroup中的ip_list为[]，且类型为白名单时，表示禁止所有ip的访问。当关联的ipgroup中的ip_list为[]，且类型为黑名单时，表示允许所有ip的访问。最小长度：1 最大长度：36
enable_ipgroup	否	Boolean	访问控制组的状态。取值： true：开启访问控制，默认值。 flase：关闭访问控制。
type	否	String	访问控制组的类型。 white：白名单，只允许指定ip访问，默认值。 black：黑名单，不允许指定ip访问。

表8 CreateListenerQuicConfigOption
参数	是否必选	参数类型	描述
quic_listener_id	是	String	监听器关联的QUIC监听器ID。指定的listener id必须已存在，且协议类型为QUIC，不能指定为null，否则与enable_quic_upgrade冲突。
enable_quic_upgrade	否	Boolean	QUIC升级的开启状态。 True:开启QUIC升级； Flase：关闭QUIC升级（默认）。开启HTTPS监听器升级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表示不限制，默认为-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协议。使用说明：仅HTTPS协议监听器有效。 QUIC监听器不能设置该字段，固定返回为true。其他协议的监听器可设置该字段但无效，无论取值如何都不影响监听器正常运行。
id	String	监听器ID。
insert_headers	ListenerInsertHeaders object	可选的HTTP头插入，可以将从负载均衡器到后端云服务器的路径中需要被后端云服务器用到的信息写入HTTP中，随报文传递到后端云服务器使。例如可通过X-Forwarded-ELB-IP开关，将负载均衡器的弹性公网IP传到后端云服务器。
loadbalancers	Array of LoadBalancerRef objects	监听器所属的负载均衡器的ID列表。一个监听器只支持关联到一个LB。
name	String	监听器的名称。注意：若名称为空，则在控制台的监听器列表无法选择并查看监听器详情。
project_id	String	监听器所在的项目ID。
protocol	String	监听器的监听协议。取值：TCP、UDP、HTTP、HTTPS、TERMINATED_HTTPS、QUIC、TCPSSL。使用说明：共享型LB上的HTTPS监听器只支持设置为TERMINATED_HTTPS，创建时传入HTTPS将会自动转为TERMINATED_HTTPS。独享型LB上的HTTPS监听器只支持设置为HTTPS，创建时传入TERMINATED_HTTPS将会自动转为HTTPS。
protocol_port	Integer	监听器的监听端口。QUIC监听器端口不能是4789，且不能和UDP监听器端口重复。传0时表示开启监听端口范围的能力，此时port_ranges为必填字段。最小值：0 最大值：65535
sni_container_refs	Array of strings	监听器使用的SNI证书（带域名的服务器证书）ID列表。使用说明：列表对应的所有SNI证书的域名不允许存在重复。列表对应的所有SNI证书的域名总数不超过50。
sni_match_algo	String	监听器使用的SNI证书泛域名匹配方式。 longest_suffix表示最长尾缀匹配，wildcard表示标准域名分级匹配。默认为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 不开启重试。默认：true。使用说明：若关联是共享型LB，仅在protocol为HTTP、TERMINATED_HTTPS时才能传入该字段。若关联是独享型LB，仅在protocol为HTTP、HTTPS和QUIC时才能传入该字段。
keepalive_timeout	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_timeout	Integer	等待后端服务器响应超时时间。请求转发后端服务器后，在等待超时member_timeout时长没有响应，负载均衡将终止等待，并返回 HTTP504错误码。取值：1-300s，默认为60s。使用说明：仅支持协议为HTTP/HTTPS的监听器。
ipgroup	ListenerIpGroup object	listener对象中的ipgroup信息
transparent_client_ip_enable	Boolean	是否透传客户端IP地址。开启后客户端IP地址将透传到后端服务器。仅作用于共享型LB的TCP/UDP监听器。取值：共享型LB的TCP/UDP监听器可设置为true或false，不传默认为false。共享型LB的HTTP/HTTPS监听器只支持设置为true，不传默认为true。独享型负载均衡器所有协议的监听器只支持设置为true，不传默认为true。使用说明：开启特性后，ELB和后端服务器之间直接使用真实的IP访问，需要确保已正确设置服务器的安全组以及访问控制策略。开启特性后，不支持同一台服务器既作为后端服务器又作为客户端的场景。开启特性后，不支持变更后端服务器规格。
proxy_protocol_enable	Boolean	是否开启proxy_protocol。仅tcpssl监听器可指定，其他协议的监听器该字段不生效，proxy_protocol不开启。
enhance_l7policy_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*
quic_config	ListenerQuicConfig object	当前监听器关联的QUIC监听器配置信息，仅protocol为HTTPS时有效。对于TCP/UDP/HTTP/QUIC监听器，若该字段非空则报错。说明：客户端向服务端发送正常的HTTP协议请求并携带了支持QUIC协议的信息。如果服务端监听器开启了升级QUIC，那么就会在响应头中加入服务端支持的QUIC端口和版本信息。客户端再次请求时会同时发送TCP(HTTPS)和UDP(QUIC)请求，若QUIC请求成功，则后续继续使用QUIC交互。

**表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头带到后端云服务器。

**表12** LoadBalancerRef
参数	参数类型	描述
id	String	负载均衡器ID。

**表13** Tag
参数	参数类型	描述
key	String	标签键最小长度：1 最大长度：36
value	String	标签值最小长度：0 最大长度：43

**表14** ListenerIpGroup
参数	参数类型	描述
ipgroup_id	String	监听器关联的访问控制组的id。创建时必选，更新时非必选。指定的ipgroup必须已存在，不能指定为null，否则与enable_ipgroup冲突。
enable_ipgroup	Boolean	访问控制组的状态。 True:开启访问控制； Flase：关闭访问控制；开启访问控制的监听器，允许直接删除。
type	String	访问控制组的类型。 white:白名单，只允许指定ip访问； black:黑名单，不允许指定ip访问；

**表15** ListenerQuicConfig
参数	参数类型	描述
quic_listener_id	String	监听器关联的QUIC监听器ID。创建时必选，更新时非必选。指定的listener id必须已存在，且协议类型为QUIC，不能指定为null，否则与enable_quic_upgrade冲突。
enable_quic_upgrade	Boolean	QUIC升级的开启状态。 True:开启QUIC升级； Flase：关闭QUIC升级；开启HTTPS监听器升级QUIC监听器能力

请求示例

示例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-0",
    "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
  },
  "request_id" : "f4c4aca8-df16-42e8-8836-33e4b8e9aa8e"
}

状态码

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

错误码

请参见错误码。

创建监听器