更新时间:2022-01-25 GMT+08:00

更新监听器

功能介绍

更新监听器。

接口约束

如果listener关联的load balancer的provisioning 状态不是ACTIVE,则不能更新该listener。 只有管理员用户才能指定connection_limit的值。

URI

PUT /v3/{project_id}/elb/listeners/{listener_id}

表1 路径参数

参数

是否必选

参数类型

描述

listener_id

String

监听器ID

project_id

String

租户ID

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

IAM鉴权Token

表3 请求Body参数

参数

是否必选

参数类型

描述

listener

UpdateListenerOption object

监听器对象。

表4 UpdateListenerOption

参数

是否必选

参数类型

描述

admin_state_up

Boolean

监听器的管理状态。只能设置为true。

不支持该字段,请勿使用。

client_ca_tls_container_ref

String

监听器使用的CA证书ID。

default_pool_id

String

监听器的默认后端云服务器组ID。当请求没有匹配的转发策略时,转发到默认后端云服务器上处理。

最小长度:1

最大长度:36

default_tls_container_ref

String

监听器使用的服务器证书ID。

description

String

监听器的描述信息

最小长度:1

最大长度:255

http2_enable

Boolean

HTTP2功能的开启状态。该字段只有当监听器的协议是HTTPS时才有意义,开启后,可提升客户端与负载均衡间的访问性能,负载均衡与后端服务器间仍采用HTTP1.X协议。其他协议该字段无效,即无论取值如何都不影响监听器正常运行

缺省值:true

insert_headers

ListenerInsertHeaders object

可选的HTTP头插入,可以将从负载均衡器到后端云服务器的路径中需要被后端云服务器用到的信息写入HTTP中,随报文传递到后端云服务器使。例如可通过X-Forwarded-ELB-IP开关,将负载均衡器的弹性公网IP传到后端云服务器。

name

String

监听器名称

最小长度:1

最大长度:255

sni_container_refs

Array of strings

监听器使用的SNI证书(带域名的服务器证书)ID的列表。 各SNI证书的域名不允许重复。 各SNI证书域名总数不超过30。

非HTTPS协议的监听器传入sni_container_refs字段将被忽略并返回[]。

tls_ciphers_policy

String

监听器使用的安全策略,仅对HTTPS协议类型的监听器有效。默认值为tls-1-0。

其他协议不支持该字段,若设置则报错。

取值范围:

  • tls-1-0
  • tls-1-1
  • tls-1-2
  • tls-1-2-strict

enable_member_retry

Boolean

是否关闭后端服务器的重试。 当前仅七层的共享型实例支持指定该字段。

缺省值:false

member_timeout

Integer

等待后端服务器请求超时时间,仅限协议为HTTP,HTTPS的监听器配置。取值范围为1-300s,默认为60s。

TCP和UDP监听器不支持此字段。

client_timeout

Integer

等待客户端请求超时时间,仅限协议为HTTP,HTTPS的监听器配置。取值范围为1-60s,默认为60s。

TCP和UDP监听器不支持此字段。

keepalive_timeout

Integer

TCP监听器配置空闲超时时间,取值范围为(10-900s)默认值为300s。

HTTP/HTTPS监听器为客户端连接空闲超时时间,取值范围为(1-300s)默认值为15s。

UDP监听器不支持此字段。

ipgroup

UpdateListenerIpGroupOption object

listener对象中的ipgroup信息,可以传null或{},表示移除监听器的访问控制组。

若监听器更新前无访问控制组,需要绑定访问控制组则必须传入ipgroup_id字段。

不支持该字段,请勿使用。

transparent_client_ip_enable

Boolean

是否透传请求客户端ip地址。TCP/UDP监听器可设置为true或false,默认为false;HTTP/HTTPS监听器只支持设置为true,默认为true。 共享型实例的TCP/UDP监听器支持修改。共享型实例的HTTP/HTTPS监听器和独享型实例的所有类型监听器都不支持修改。

enhance_l7policy_enable

Boolean

是否开启了高级转发策略的功能。true表示开启,false表示关闭。开启后不可关闭。开启后,如下字段才会生效:

  • redirect_url_config,详见l7policy。
  • fixed_response_config,详见l7policy。
  • priority,详见l7policy。
  • conditions,详见l7rule。

不支持该字段,请勿使用。

表5 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

表6 UpdateListenerIpGroupOption

参数

是否必选

参数类型

描述

ipgroup_id

String

监听器关联的访问控制组的id。

当关联的ipgroup中的ip_list为[],且类型为白名单时,表示禁止所有ip的访问。

当关联的ipgroup中的ip_list为[],且类型为黑名单时,表示允许所有ip的访问。

指定的ipgroup必须已存在,不能指定为null,否则与enable_ipgroup冲突。

enable_ipgroup

Boolean

访问控制组的状态。 True:开启访问控制; Flase:关闭访问控制; 开启访问控制的监听器,允许直接删除。

type

String

访问控制组的类型。 white:白名单,只允许指定ip访问; black:黑名单,不允许指定ip访问;

响应参数

状态码: 200

表7 响应Body参数

参数

参数类型

描述

request_id

String

请求ID。

注:自动生成 。

listener

Listener object

监听器对象。

表8 Listener

参数

参数类型

描述

admin_state_up

Boolean

监听器的管理状态。只能设置为true。

不支持该字段,请勿使用。

缺省值:true

client_ca_tls_container_ref

String

监听器使用的CA证书ID。

connection_limit

Integer

监听器的最大连接数,默认为-1。

不支持该字段,请勿使用。

created_at

String

监听器的创建时间。

default_pool_id

String

监听器的默认后端云服务器组ID。当请求没有匹配的转发策略时,转发到默认后端云服务器上处理。

default_tls_container_ref

String

监听器使用的服务器证书ID。

description

String

监听器的描述信息

http2_enable

Boolean

HTTP2功能的开启状态。该字段只有当监听器的协议是HTTPS时才有意义,开启后,可提升客户端与负载均衡间的访问性能,负载均衡与后端服务器间仍采用HTTP1.X协议。其他协议该字段无效,即无论取值如何都不影响监听器正常运行

缺省值:true

id

String

监听器ID

insert_headers

ListenerInsertHeaders object

可选的HTTP头插入,可以将从负载均衡器到后端云服务器的路径中需要被后端云服务器用到的信息写入HTTP中,随报文传递到后端云服务器使。例如可通过X-Forwarded-ELB-IP开关,将负载均衡器的弹性公网IP传到后端云服务器。

loadbalancers

Array of LoadBalancerRef objects

监听器绑定的负载均衡器ID的列表。

name

String

监听器名称

project_id

String

监听器所在的项目ID。

protocol

String

监听器的监听协议

protocol_port

Integer

监听器的监听端口。

最小值:1

最大值:65535

sni_container_refs

Array of strings

监听器使用的SNI证书(带域名的服务器证书)ID的列表。 各SNI证书的域名不允许重复。 各SNI证书域名总数不超过30。

非HTTPS协议的监听器传入sni_container_refs字段将被忽略并返回[]。

tags

Array of Tag objects

标签列表

updated_at

String

监听器的更新时间。

tls_ciphers_policy

String

监听器使用的安全策略,仅对HTTPS协议类型的监听器有效,且默认值为tls-1-0。 取值包括:tls-1-0, tls-1-1, tls-1-2, tls-1-2-strict四种安全策略。

enable_member_retry

Boolean

是否关闭后端服务器的重试。 该字段只在protocol为HTTP、HTTPS时有意义。

keepalive_timeout

Integer

TCP监听器配置空闲超时时间,取值范围为(10-900s)默认值为300s,TCP监听器配置空闲超时时间,取值范围为(10-900s)默认值为300s。

HTTP/HTTPS监听器为客户端连接空闲超时时间,取值范围为(1-300s)默认值为15s。

UDP监听器不支持此字段。

client_timeout

Integer

等待客户端请求超时时间,仅限协议为HTTP,HTTPS的监听器配置。取值范围为1-60s, 默认值为60s。

TCP和UDP监听器不支持此字段。

member_timeout

Integer

等待后端服务器请求超时时间。仅限协议为HTTP,HTTPS的监听器配置,取值范围为1-300s,默认为60s。

TCP和UDP监听器不支持此字段。

ipgroup

ListenerIpGroup object

listener对象中的ipgroup信息。

不支持该字段,请勿使用。

transparent_client_ip_enable

Boolean

是否透传请求客户端ip地址。 共享型负载均衡器的TCP/UDP监听器可设置为true或false,不传默认为false;HTTP/HTTPS监听器只支持设置为true,不传默认为true。 独享型负载均衡器所有协议的监听器只能设置为true,不传默认为true。

enhance_l7policy_enable

Boolean

是否开启了高级转发策略的功能。默认:false - 不开启。开启后,如下字段才会生效:

  • redirect_url_config,详见l7policy。
  • fixed_response_config,详见l7policy。
  • priority,详见l7policy。
  • conditions,详见l7rule。

不支持该字段,请勿使用。

表9 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

表10 LoadBalancerRef

参数

参数类型

描述

id

String

负载均衡器ID。

表11 Tag

参数

参数类型

描述

key

String

功能描述:标签键

value

String

功能描述:标签值

表12 ListenerIpGroup

参数

参数类型

描述

ipgroup_id

String

监听器关联的访问控制组的id。

当关联的ipgroup中的ip_list为[],且类型为白名单时,表示禁止所有ip的访问。

当关联的ipgroup中的ip_list为[],且类型为黑名单时,表示允许所有ip的访问。

指定的ipgroup必须已存在,不能指定为null,否则与enable_ipgroup冲突。

enable_ipgroup

Boolean

访问控制组的状态。 True:开启访问控制; Flase:关闭访问控制; 开启访问控制的监听器,允许直接删除。

type

String

访问控制组的类型。 white:白名单,只允许指定ip访问; black:黑名单,不允许指定ip访问;

请求示例

PUT

https://{elb_endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners/0b11747a-b139-492f-9692-2df0b1c87193

{
  "listener" : {
    "description" : "My listener update.",
    "name" : "listener-1",
    "http2_enable" : true
  }
}

响应示例

状态码: 200

操作正常返回。

{
  "listener" : {
    "id" : "e2baad06-8095-4159-a14e-d1f0137bac06",
    "name" : "listener-1",
    "protocol_port" : 77,
    "protocol" : "HTTP",
    "description" : "My listener update.",
    "admin_state_up" : true,
    "loadbalancers" : [ {
      "id" : "c285bc7b-56d5-43bd-9589-075ee0a5c777"
    } ],
    "project_id" : "060576782980d5762f9ec014dd2f1148",
    "sni_container_refs" : [ ],
    "connection_limit" : -1,
    "default_pool_id" : "61609d20-5230-4b72-8274-46212bbf317c",
    "tags" : [ ],
    "created_at" : "2020-07-28T11:35:21Z",
    "updated_at" : "2020-07-28T11:35:21Z",
    "http2_enable" : true,
    "insert_headers" : {
      "X-Forwarded-ELB-IP" : false,
      "X-Forwarded-Host" : true,
      "X-Forwarded-For-Port" : false,
      "X-Forwarded-Port" : false
    },
    "member_timeout" : 60,
    "client_timeout" : 60,
    "keepalive_timeout" : 60,
    "enable_member_retry" : true,
    "transparent_client_ip_enable" : true,
    "enhance_l7policy_enable" : false
  },
  "request_id" : "619dc40f7ec73c0f13b5b5127904b71e"
}

状态码

状态码

描述

200

操作正常返回。

错误码

请参见错误码