文档首页/弹性负载均衡 ELB/API参考（联盟区域）/API（V3）/后端服务器组/更新后端服务器组
更新时间：2026-01-16 GMT+08:00
在线调试
CLI示例
查看PDF
分享

更新后端服务器组

功能介绍

更新后端服务器组。

接口约束

如果与pool绑定的load balancer的provisioning status不是ACTIVE，则不能更新该pool。

调用方法

请参见如何调用API。

URI

PUT /v3/{project_id}/elb/pools/{pool_id}

表1 路径参数

参数

是否必选

参数类型

描述

pool_id

是

String

参数解释：后端服务器组ID。

约束限制：不涉及

取值范围：不涉及

默认取值：不涉及

project_id

是

String

参数解释：项目ID。获取方式请参见获取项目ID。

约束限制：不涉及

取值范围：长度为32个字符，由小写字母和数字组成。

默认取值：不涉及

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：IAM鉴权Token。

约束限制：不涉及

取值范围：不涉及

默认取值：不涉及

表3 请求Body参数

参数

是否必选

参数类型

描述

pool

是

UpdatePoolOption object

参数解释：更新后端服务器组请求参数。

约束限制：不涉及

表4 UpdatePoolOption

参数

是否必选

参数类型

描述

admin_state_up

否

Boolean

参数解释：后端服务器组的管理状态。

约束限制：只支持更新为true。

取值范围：true 启用。

默认取值：不涉及

description

否

String

参数解释：后端服务器组的描述信息。

约束限制：不涉及

取值范围：不涉及

默认取值：不涉及

lb_algorithm

否

String

参数解释：后端服务器组的负载均衡算法。

约束限制：

  • 当该字段的取值为SOURCE_IP或QUIC_CID时，后端服务器组绑定的后端服务器的weight字段无效。

  • 只有pool的protocol为QUIC时，才支持QUIC_CID算法。

取值范围：

  • ROUND_ROBIN：加权轮询算法。

  • LEAST_CONNECTIONS：加权最少连接算法。

  • SOURCE_IP：源IP算法。

  • QUIC_CID：连接ID算法。

  • 2_TUPLE_HASH：二元组hash算法，仅IP类型的pool支持。

  • 3_TUPLE_HASH：三元组hash算法，仅IP类型的pool支持。

  • 5_TUPLE_HASH：五元组hash算法，仅IP类型的pool支持。

  • IP型pool不指定该字段时，默认设置为5_TUPLE_HASH。

默认取值：不涉及

name

否

String

参数解释：后端服务器组的名称。

约束限制：不涉及

取值范围：不涉及

默认取值：不涉及

session_persistence

否

UpdatePoolSessionPersistenceOption object

参数解释：会话持久性对象。

约束限制：慢启动与会话保持不能同时开启。若都开启则会导致会话保持失效。

slow_start

否

UpdatePoolSlowStartOption object

参数解释：慢启动信息。开启慢启动后，将会在设定的时间段（duration）内对新添加到后端服务器组的后端服务器进行预热，转发到该服务器的请求数量线性增加。

约束限制：

  • 当后端服务器组的协议为HTTP/HTTPS/GRPC时有效，其他协议传入该字段将报错。

  • 慢启动与会话保持不能同时开启。若都开启则会导致会话保持失效。

  • 网关型LB，不支持该特性，请勿使用。

member_deletion_protection_enable

否

Boolean

参数解释：是否开启后端服务器移除保护。开关开启后，不允许从该ELB后端服务器组下移除后端服务器。

约束限制：

  • 开关开启后，移除member会报错拦截，涉及如下API:

    • 级联删除负载均衡器（DELETE /v3/{project_id}/elb/loadbalancers/{loadbalancer_id}/force-elb）

    • 级联删除负载均衡器及关联EIP（POST /v3/{project_id}/elb/loadbalancers/{loadbalancer_id}/delete-cascade）

    • 级联删除监听器（DELETE /v3/{project_id}/elb/listeners/{listener_id}/force）

    • 级联删除后端服务器组（DELETE /v3/{project_id}/elb/pools/{pool_id}/delete-cascade）

    • 删除后端服务器（DELETE /v3/{project_id}/elb/pools/{pool_id}/members/{member_id}）

    • 批量删除后端服务器（POST /v3/{project_id}/elb/pools/{pool_id}/members/batch-delete）

取值范围：false 不开启，true 开启。

默认取值：false

说明：
退场时需要先关闭所有资源的删除保护开关。

vpc_id

否

String

参数解释：后端服务器组关联的虚拟私有云的ID。

约束限制：只有vpc_id为空时允许更新。

取值范围：不涉及

默认取值：不涉及

type

否

String

参数解释：后端服务器组的类型。

约束限制：

  • 只有type为空时允许更新，不允许从非空更新为空。

  • instance：允许任意类型的后端，type指定为该类型时，vpc_id是必选字段。

  • ip：只能添加IP类型后端，type指定为该类型时，vpc_id不允许指定。pool的protocol为IP时，type不允许设置为ip。

  • 空字符串（""）：允许任意类型的后端

取值范围：不涉及

默认取值：不涉及

quic_cid_hash_strategy

否

QuicCidHashStrategy object

参数解释：后端服务器组基于部分DST CID的多径分发策略配置。

约束限制：不涉及

az_affinity

否

UpdateAzAffinity object

参数解释：后端服务器组的可用区亲和策略配置。

约束限制：不涉及

表5 UpdatePoolSessionPersistenceOption

参数

是否必选

参数类型

描述

cookie_name

否

String

参数解释：cookie名称。

约束限制：

  • 只有当type为APP_COOKIE时才有效。其他情况下传该字段会报错。

  • 网关型LB，不支持该特性，请勿使用。

取值范围：最大长度1024个字符。

默认取值：不涉及

type

否

String

参数解释：会话保持类型。

取值范围：

  • SOURCE_IP：基于源IP地址的会话保持，也就是根据客户端的源IP地址将流量持续转发到同一后端服务器（member）。

  • HTTP_COOKIE：通过在HTTP响应中插入一个特殊的Cookie，实现会话保持。负载均衡会在后续请求中识别该Cookie，并将请求转发到对应的后端服务器。

  • APP_COOKIE：基于应用层Cookie的会话保持。与HTTP_COOKIE不同的是，APP_COOKIE要求后端服务在响应中插入一个指定名称的Cookie，负载均衡器识别后，将后续请求转发到相同后端member。

默认取值：不涉及

persistence_timeout

否

Integer

参数解释：会话保持的时间。

约束限制：当type为APP_COOKIE时不生效。

取值范围：

  • 如果pool的protocol为TCP、UDP和QUIC，则范围为[1,60]（分钟）。

  • 如果pool的protocol为HTTP和HTTPS，则范围为[1,1440]（分钟）。

默认取值：不涉及

表6 UpdatePoolSlowStartOption

参数

是否必选

参数类型

描述

enable

否

Boolean

参数解释：慢启动的开关。

约束限制：不涉及

取值范围：true 开启，false 关闭。

默认取值：不涉及

duration

否

Integer

参数解释：慢启动的持续时间。

约束限制：不涉及

取值范围：30~1200，单位：秒。

默认取值：不涉及

表7 QuicCidHashStrategy

参数

是否必选

参数类型

描述

len

是

Integer

参数解释：表示hash的时候取CID的长度。

约束限制：仅当负载均衡算法为QUIC_CID的时候才生效。

取值范围：1-20

默认取值：3

offset

是

Integer

参数解释：表示hash的时候取CID的偏移量。

约束限制：仅当负载均衡算法为QUIC_CID的时候才生效。

取值范围：0-19

默认取值：1

表8 UpdateAzAffinity

参数

是否必选

参数类型

描述

enable

否

Boolean

参数解释：后端服务器组可用区亲和开关。

约束限制：

  • 当后端服务器组中有未设置availability_zone属性的IP类型后端服务器时无法开启可用区亲和。

  • 当后端服务器绑定TLS监听器时无法开启可用区亲和。

  • 仅IP、UDP、TCP类型的后端服务器组支持开启可用区亲和。

  • 当开启可用区亲和后，原本的pool_health配置失效。

取值范围：true或false，true表示开启，false表示关闭。

默认取值：不涉及

az_minimum_healthy_member_percentage

否

Integer

参数解释：后端服务器组单可用区百分比健康度最小阈值，当“后端服务器组单可用区百分比健康度”小于该阈值时，触发可用区异常退避策略。“后端服务器组单可用区百分比健康度”是指在一个后端服务器组中，同可用区中健康检查结果正常的服务器数量与该后端服务器组中属于该可用区的后端服务器总数量的比值，百分比结果向上取整。例如：后端服务器组中属于可用区A的后端服务器总数量为3，设置后端服务器组单可用区百分比健康度最小阈值为66时，3x0.66=1.98向上取整为数量阈值2台，即属于可用区A的健康后端数小于2台时触发退避策略；设置后端服务器组单可用区百分比健康度最小阈值为67时，3x0.67=2.01向上取整为数量阈值3台，即属于可用区A的健康后端数小于3台时触发退避策略。

约束限制：

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时为-1

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时不为-1

取值范围：-1至100的整数，0-100为百分比范围，-1表示采用数量阈值。

默认取值：不涉及

az_minimum_healthy_member_count

否

Integer

参数解释：后端服务器组单可用区中数量健康度最小阈值，当“后端服务器组单可用区中数量健康度”小于该阈值时，触发可用区异常退避策略。“后端服务器组单可用区中数量健康度”是指在一个后端服务器组中，属于同一个可用区的健康检查结果正常的服务器数量。

约束限制：

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时为-1

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时不为-1

取值范围：-1至10000的整数，0-10000为数量范围，-1表示采用百分比阈值。

默认取值：不涉及

az_unhealthy_fallback_strategy

否

String

参数解释：后端服务器组单可用区异常退避策略。后端服务器组的健康度小于所配置的最小阈值时，触发该退避策略。forward_to_all_member_of_local_az：转发至同可用区的所有后端服务器，无论健康检查结果是否正常；forward_to_healthy_member_of_remote_az：转发至非同可用区中所有健康检查结果正常的后端服务器；forward_to_all_healthy_member：转发至所有可用区中健康检查结果正常的后端服务器；forward_to_all_member：转发至所有可用区中的所有后端服务器，无论健康检查结果是否正常

约束限制：不涉及

取值范围：forward_to_all_member_of_local_az，forward_to_healthy_member_of_remote_az，forward_to_all_healthy_member，forward_to_all_member。

默认取值：forward_to_all_member_of_local_az

响应参数

状态码：200

表9 响应Body参数

参数

参数类型

描述

request_id

String

参数解释：请求ID。

取值范围：由数字、小写字母和中划线（-）组成的字符串，自动生成。

pool

Pool object

参数解释：后端服务器组对象。

表10 Pool

参数

参数类型

描述

admin_state_up

Boolean

参数解释：后端服务器组的管理状态。只支持设置为true。

取值范围：true 启用。

az_affinity

AzAffinity object

参数解释：后端服务器组的可用区亲和策略配置。

description

String

参数解释：后端服务器组的描述信息。

取值范围：不涉及

healthmonitor_id

String

参数解释：后端服务器组关联的健康检查的ID。

取值范围：不涉及

id

String

参数解释：后端服务器组的ID。

取值范围：不涉及

lb_algorithm

String

参数解释：后端服务器组的负载均衡算法。

取值范围：

  • ROUND_ROBIN：加权轮询算法。

  • LEAST_CONNECTIONS：加权最少连接算法。

  • SOURCE_IP：源IP算法。

  • QUIC_CID：连接ID算法。

  • 2_TUPLE_HASH：二元组hash算法，仅IP类型的pool支持。

  • 3_TUPLE_HASH：三元组hash算法，仅IP类型的pool支持。

  • 5_TUPLE_HASH：五元组hash算法，仅IP类型的pool支持。

  • IP型pool不指定该字段时，默认设置为5_TUPLE_HASH。

listeners

Array of ListenerRef objects

参数解释：后端服务器组关联的监听器ID列表。

members

Array of MemberRef objects

参数解释：后端服务器组中的后端服务器ID列表。

name

String

参数解释：后端服务器组的名称。

取值范围：不涉及

project_id

String

参数解释：后端服务器组所在的项目ID。

取值范围：不涉及

protocol

String

参数解释：后端服务器组的后端协议。

取值范围：TCP、UDP、IP、TLS、GRPC、HTTP、HTTPS和QUIC。

session_persistence

SessionPersistence object

参数解释：会话持久性对象。

ip_version

String

参数解释：后端服务器组支持的IP版本。

slow_start

SlowStart object

参数解释：慢启动信息。开启慢启动后，将会在设定的时间段（duration）内对新添加到后端服务器组的后端服务器进行预热，转发到该服务器的请求数量线性增加。

member_deletion_protection_enable

Boolean

参数解释：是否开启后端服务器移除保护。开关开启后，不允许从该ELB后端服务器组下移除后端服务器。

取值范围：false不开启，true开启。

说明：
退场时需要先关闭所有资源的删除保护开关。

created_at

String

参数解释：创建时间。

取值范围：格式：yyyy-MM-dd'T'HH:mm:ss'Z'，UTC时区。

updated_at

String

参数解释：更新时间。

取值范围：格式：yyyy-MM-dd'T'HH:mm:ss'Z'，UTC时区。

vpc_id

String

参数解释：后端服务器组关联的虚拟私有云的ID。

取值范围：不涉及

type

String

参数解释：后端服务器组的类型。

取值范围：

  • instance：允许任意类型的后端，type指定为该类型时，vpc_id是必选字段。

  • ip：只能添加IP类型后端，type指定为该类型时，vpc_id不允许指定。pool的protocol为IP时，type不允许设置为ip。]

  • 空字符串（""）：允许任意类型的后端

any_port_enable

Boolean

参数解释：后端是否开启全端口转发。开启后，后端服务器端口与前端监听器端口保持一致。关闭后，请求会转发给后端服务器protocol_port字段指定端口。

取值范围：false 不开启，true 开启。

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

connection_drain

ConnectionDrain object

参数解释：后端服务器的延迟注销的功能配置（只针对TCP、UDP、QUIC协议类型的后端服务器组和TCP、UDP协议类的监听器）。

以下场景会触发：

  • 后端服务器从后端服务器组中移除。

  • 后端服务器健康检查状态异常。

  • 后端服务器权重修改为0。

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

enterprise_project_id

String

参数解释：资源所属的企业项目ID。

取值范围：

  • "0"：表示资源属于default企业项目。

  • UUID格式的字符串，表示非默认企业项目。

pool_health

PoolHealth object

参数解释：后端全下线转发配置。

public_border_group

String

参数解释：公网边界组。

取值范围：

  • center：表示中心站点的公网边界组

  • 边缘站点名称：表示边缘站点的公网边界组

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

quic_cid_hash_strategy

QuicCidHashStrategy object

参数解释：后端服务器组基于部分DST CID的多径分发策略配置。

表11 AzAffinity

参数

参数类型

描述

enable

Boolean

参数解释：后端服务器组是否开启可用区亲和。开启后，负载均衡器会按照配置的亲和策略进行转发。

约束限制：

  • 仅IP,TCP,UDP的pool支持。

  • TLS监听器绑定的pool不支持。

  • 开启后，原本的pool_health配置失效。

取值范围：false不开启，true开启。

默认取值：不涉及

az_minimum_healthy_member_percentage

Integer

参数解释：后端服务器组单可用区百分比健康度最小阈值，当“后端服务器组单可用区百分比健康度”小于该阈值时，触发可用区异常退避策略。“后端服务器组单可用区百分比健康度”是指在一个后端服务器组中，同可用区中健康检查结果正常的服务器数量与该后端服务器组中属于该可用区的后端服务器总数量的比值，百分比结果向上取整。例如：后端服务器组中属于可用区A的后端服务器总数量为3，设置后端服务器组单可用区百分比健康度最小阈值为66时，3x0.66=1.98向上取整为数量阈值2台，即属于可用区A的健康后端数小于2台时触发退避策略；设置后端服务器组单可用区百分比健康度最小阈值为67时，3x0.67=2.01向上取整为数量阈值3台，即属于可用区A的健康后端数小于3台时触发退避策略。

约束限制：

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时为-1

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时不为-1

取值范围：-1至100的整数，0-100为百分比范围，-1表示采用数量阈值。

默认取值：不涉及

az_minimum_healthy_member_count

Integer

参数解释：后端服务器组单可用区中数量健康度最小阈值，当“后端服务器组单可用区中数量健康度”小于该阈值时，触发可用区异常退避策略。“后端服务器组单可用区中数量健康度”是指在一个后端服务器组中，属于同一个可用区的健康检查结果正常的服务器数量。

约束限制：

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时为-1

  • enable为true时，az_minimum_healthy_member_percentage与az_minimum_healthy_member_count不能同时不为-1

取值范围：-1至10000的整数，0-10000为数量范围，-1表示采用百分比阈值。

默认取值：不涉及

az_unhealthy_fallback_strategy

String

参数解释：后端服务器组单可用区异常退避策略。后端服务器组的健康度小于所配置的最小阈值时，触发该退避策略。forward_to_all_member_of_local_az：转发至同可用区的所有后端服务器，无论健康检查结果是否正常；forward_to_healthy_member_of_remote_az：转发至非同可用区中所有健康检查结果正常的后端服务器；forward_to_all_healthy_member：转发至所有可用区中健康检查结果正常的后端服务器；forward_to_all_member：转发至所有可用区中的所有后端服务器，无论健康检查结果是否正常

约束限制：不涉及

取值范围：forward_to_all_member_of_local_az，forward_to_healthy_member_of_remote_az，forward_to_all_healthy_member，forward_to_all_member。

默认取值：forward_to_all_member_of_local_az

表12 ListenerRef

参数

参数类型

描述

id

String

参数解释：监听器ID。

取值范围：不涉及

表13 MemberRef

参数

参数类型

描述

id

String

参数解释：后端服务器ID。

取值范围：不涉及

表14 SessionPersistence

参数

参数类型

描述

cookie_name

String

参数解释：cookie名称。

取值范围：最大长度1024个字符。

type

String

参数解释：会话保持类型。

取值范围：

  • SOURCE_IP：基于源IP地址的会话保持，也就是根据客户端的源IP地址将流量持续转发到同一后端服务器（member）。

  • HTTP_COOKIE：通过在HTTP响应中插入一个特殊的Cookie，实现会话保持。负载均衡会在后续请求中识别该Cookie，并将请求转发到对应的后端服务器。

  • APP_COOKIE：基于应用层Cookie的会话保持。与HTTP_COOKIE不同的是，APP_COOKIE要求后端服务在响应中插入一个指定名称的Cookie，负载均衡器识别后，将后续请求转发到相同后端member。

persistence_timeout

Integer

参数解释：会话保持的时间。当type为APP_COOKIE时不生效。

取值范围：

  • 若pool的protocol为TCP、UDP和QUIC则范围为[1,60]（分钟），默认值1。

  • 若pool的protocol为HTTP和HTTPS则范围为[1,1440]（分钟），默认值1440。

表15 SlowStart

参数

参数类型

描述

enable

Boolean

参数解释：慢启动的开关。

取值范围：

  • true：开启。

  • false：关闭。

duration

Integer

参数解释：慢启动的持续时间。

取值范围：30-1200，单位：秒。

表16 ConnectionDrain

参数

参数类型

描述

enable

Boolean

参数解释：延迟注销功能开关。

约束限制：不涉及

取值范围：true 开启，false 关闭。

默认取值：不涉及

timeout

Integer

参数解释：延迟注销时间。

约束限制：不涉及

取值范围：10~4000，单位：秒。

默认取值：不涉及

表17 PoolHealth

参数

参数类型

描述

minimum_healthy_member_count

Integer

参数解释：当健康检查在线的member个数小于该个数，判定pool的state为不健康。

取值范围：

  • 0：默认值，不生效。

  • 1：全下线转发生效。

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

表18 QuicCidHashStrategy

参数

参数类型

描述

len

Integer

参数解释：表示hash的时候取CID的长度。

约束限制：仅当负载均衡算法为QUIC_CID的时候才生效。

取值范围：1-20

默认取值：3

offset

Integer

参数解释：表示hash的时候取CID的偏移量。

约束限制：仅当负载均衡算法为QUIC_CID的时候才生效。

取值范围：0-19

默认取值：1

请求示例

更新后端服务组的负载均衡算法

PUT https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/pools/36ce7086-a496-4666-9064-5ba0e6840c75

{
  "pool" : {
    "name" : "My pool.",
    "description" : "My pool update",
    "lb_algorithm" : "LEAST_CONNECTIONS"
  }
}

响应示例

状态码：200

操作正常返回。

{
  "pool" : {
    "name" : "my pool",
    "id" : "00ed68a5-8784-424e-8936-8dbb7a9d41e9",
    "description" : "",
    "lb_algorithm" : "ROUND_ROBIN",
    "protocol" : "TCP",
    "admin_state_up" : true,
    "loadbalancers" : [ ],
    "type" : "instance",
    "project_id" : "0c1503d710984bad92306faea3654dfd",
    "enterprise_project_id" : "0",
    "session_persistence" : null,
    "slow_start" : null,
    "healthmonitor_id" : "a5f47d4c-1187-402f-849c-c0a7767e36f5",
    "listeners" : [ ],
    "members" : [ {
      "id" : "87b1130c-80dc-493d-b98a-add98ea4c6a2"
    } ],
    "ip_version" : "dualstack",
    "member_deletion_protection_enable" : false,
    "created_at" : "2024-08-19T17:49:53Z",
    "updated_at" : "2024-09-09T09:21:05Z",
    "protection_status" : "nonProtection",
    "protection_reason" : "",
    "vpc_id" : "651594cf-18a0-4a77-942f-1a4ae216c123",
    "connection_drain" : {
      "enable" : true,
      "timeout" : 300
    },
    "pool_health" : {
      "minimum_healthy_member_count" : 0
    },
    "az_affinity" : {
      "enable" : true,
      "az_minimum_healthy_member_percentage" : -1,
      "az_minimum_healthy_member_count" : 1,
      "az_unhealthy_fallback_strategy" : "forward_to_all_member_of_local_az"
    },
    "quic_cid_hash_strategy" : null,
    "public_border_group" : "center",
    "any_port_enable" : false
  },
  "request_id" : "2d974978-0733-404d-a21a-b29204f4803a"
}

状态码

状态码

描述

200

操作正常返回。

错误码

请参见错误码。

父主题：后端服务器组