全部产品
Search

搜索本产品

    负载均衡：UpdateServerGroupAttribute - 更新服务器组配置

    文档中心

    负载均衡：UpdateServerGroupAttribute - 更新服务器组配置

    更新时间：Jan 21, 2026

    更新服务器组的配置，例如健康检查、会话保持、名称、调度算法和协议等。

    接口说明

    UpdateServerGroupAttribute 接口属于异步接口，即系统返回一个请求 ID，但该服务器组的配置尚未更新成功，系统后台的更新任务仍在进行。您可以调用 ListServerGroups 查询服务器组的配置的更新状态：

    • 当服务器组的配置处于 Configuring 状态时，表示服务器组的配置正在更新中。

    • 当服务器组的配置处于 Available 状态时，表示服务器组的配置更新成功。

    调试

    您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

    调试

    授权信息

    下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

    • 操作：是指具体的权限点。

    • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

    • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

      • 对于必选的资源类型，用前面加 * 表示。

      • 对于不支持资源级授权的操作，用全部资源表示。

    • 条件关键字：是指云产品自身定义的条件关键字。

    • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

    操作

    访问级别

    资源类型

    条件关键字

    关联操作

    alb:UpdateServerGroupAttribute

    update

    *ServerGroup

    acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}

    		 无 无

    请求参数

    名称

    类型

    必填

    描述

    示例值
    ServerGroupName

    string

    否

    服务器组名称。

    长度为 2~128 个英文或中文字符，必须以大小字母或中文开头，可包含数字，半角句号（.），下划线（_）和短划线（-）。

    test
    Scheduler

    string

    否

    调度算法。取值：

    • Wrr：加权轮询，权重值越高的后端服务器，被轮询到的次数（概率）也越高。

    • Wlc：加权最小连接数，除了根据每台后端服务器设定的权重值来进行轮询，同时还考虑后端服务器的实际负载（即连接数）。当权重值相同时，当前连接数越小的后端服务器被轮询到的次数（概率）也越高。

    • Sch：一致性哈希，相同哈希因子计算结果的请求将会调度到相同的后端服务器。不配置 UchConfig 参数时，默认哈希因子为源 IP，相同源 IP 地址的请求会分发到同一台后端服务器；配置了 UchConfig 参数时，哈希因子为 URL 参数，相同 URL 参数的请求会分发到同一台后端服务器。

    Wrr
    ClientToken

    string

    否

    客户端 Token，用于保证请求的幂等性。

    从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符。

    说明

    若您未指定，则系统自动使用 API 请求的 RequestId 作为 ClientToken 标识。每次 API 请求的 RequestId 可能不一样。

    5A2CFF0E-5718-45B5-9D4D-70B3******
    DryRun

    boolean

    否

    是否只预检此次请求，取值：

    • true：发送检查请求，不会修改资源。检查项包括是否填写了必需参数、请求格式、业务限制。如果检查不通过，则返回对应错误。如果检查通过，则返回错误码DryRunOperation。

    • false（默认值）：发送正常请求，通过检查后返回 HTTP 2xx状态码并直接进行操作。

    true
    HealthCheckConfig

    object

    否

    健康检查相关配置结构体。

    HealthCheckConnectPort

    integer

    否

    健康检查的后端服务器的端口。

    取值范围：0~65535。

    设置为 0 时代表使用后端服务器的端口进行健康检查。

    说明

    当前服务器组 HealthCheckEnabled 为 true 时，该参数配置生效。

    80
    HealthCheckEnabled

    boolean

    否

    是否启用健康检查，取值：

    • true：启用

    • false：不启用

    true
    HealthCheckHost

    string

    否

    健康检查域名。

    • 使用后端服务器的内网 IP（默认）：使用后端服务器的内网 IP 地址作为健康检查的域名。

    • 指定特定域名：输入一个域名。

      • 长度限制为 1~80 个字符。

      • 可包含小写字母、数字、短划线（-）和半角句号（.）。

      • 至少包含一个半角句号（.），半角句号（.）不能出现在开头或结尾。

      • 最右侧的域标签，只能包含字母，不能包含数字或短划线（-）。

      • 短划线（-）不能出现在开头或结尾。

    说明

    只有 HealthCheckProtocol 设置为 HTTP、HTTPS 或 gRPC 时，该参数生效。

    example.com
    HealthCheckCodes

    array

    否

    健康检查正常的状态码列表。

    string

    否

    健康检查正常的状态码。

    • 当 HealthCheckProtocol 取值为 HTTP 或 HTTPS 时，HealthCheckCodes 可以选择http_2xx（默认值）、 http_3xx、http_4xx和http_5xx。多个状态码用半角逗号（,）分隔。

    • 当 HealthCheckProtocol 取值为 gRPC 时，HealthCheckCodes 状态码范围：0~99，默认值：0。支持范围输入，最多支持 20 个范围值。多个范围值使用半角逗号（,）隔开。

    说明

    当前服务器组 HealthCheckEnabled 为 true 且 HealthCheckProtocol 设置为 HTTP 或 HTTPS 或 gRPC 时该参数生效。

    200
    HealthCheckHttpVersion

    string

    否

    健康检查 HTTP 协议版本。取值：

    • HTTP1.0

    • HTTP1.1

    说明

    当前服务器组 HealthCheckEnabled 为 true 且 HealthCheckProtocol 设置为 HTTP 或 HTTPS 时该参数生效。

    HTTP1.1
    HealthCheckInterval

    integer

    否

    健康检查的时间间隔。单位：秒。

    取值范围：1~50。

    说明

    当前服务器组 HealthCheckEnabled 为 true 时，该参数配置生效。

    5
    HealthCheckMethod

    string

    否

    健康检查方法。取值：

    • GET：如果响应报文长度超过 8K，会被截断，但不会影响健康检查结果的判定。

    • POST：gRPC 监听健康检查默认采用 POST 方法。

    • HEAD：HTTP 和 HTTPS 监听健康检查默认采用 HEAD 方法。

    说明

    当前服务器组 HealthCheckEnabled 为 true 且 HealthCheckProtocol 设置为 HTTP 或 HTTPS 或 gRPC 时该参数生效。

    HEAD
    HealthCheckPath

    string

    否

    健康检查的转发规则路径。

    长度限制为 1~80，只能使用字母、数字、字符-/.%?#&=以及扩展字符_;~!（)*[]@$^:',+。 URL 开头必须为/。

    说明

    当前服务器组 HealthCheckEnabled 为 true 且 HealthCheckProtocol 设置为 HTTP 或 HTTPS 时该参数生效。

    /test/index.html
    HealthCheckProtocol

    string

    否

    健康检查协议。取值：

    • HTTP：通过发送 HEAD 或 GET 请求模拟浏览器的访问行为来检查服务器应用是否健康。

    • HTTPS：通过发送 HEAD 或 GET 请求模拟浏览器的访问行为来检查服务器应用是否健康。（数据加密，相比 HTTP 更安全。）

    • TCP：通过发送 SYN 握手报文来检测服务器端口是否存活。

    • gRPC：通过发送 POST 或 GET 请求来检查服务器应用是否健康。

    HTTP
    HealthCheckTimeout

    integer

    否

    接收来自运行状况检查的响应需要等待的时间。如果后端 ECS 在指定的时间内没有正确响应，则判定为健康检查失败。单位：秒。

    取值范围：1~300。

    说明

    当前服务器组 HealthCheckEnabled 为 true 时，该参数配置生效。

    3
    HealthyThreshold

    integer

    否

    健康检查连续成功多少次后，将后端服务器的健康检查状态由 fail 判定为 success。

    取值范围：2~10。

    4
    UnhealthyThreshold

    integer

    否

    健康检查连续失败多少次后，将后端服务器的健康检查状态由 success 判定为 fail。

    取值范围：2~10。

    4
    StickySessionConfig

    object

    否

    会话保持配置结构体

    Cookie

    string

    否

    服务器上配置的 Cookie。

    长度为 1~200 个字符，只能包含 ASCII 英文字母和数字字符，不能包含半角逗号（,）、半角分号（;）或空格，也不能以美元符号（$）开头。

    说明

    当前服务器组 StickySessionEnabled 为 true 且 StickySessionType 配置为 Server 时，该参数生效。

    B490B5EBF6F3CD402E515D22B******
    CookieTimeout

    integer

    否

    Cookie 超时时间。单位：秒。

    取值范围：1~86400。

    说明

    当前服务器组 StickySessionEnabled 为 true 且 StickySessionType 配置为 Insert 时，该参数生效。

    1000
    StickySessionEnabled

    boolean

    否

    是否启用会话保持。取值：

    • true：是。

    • false：否。

    false
    StickySessionType

    string

    否

    Cookie 的处理方式。取值：

    • Insert：植入 Cookie。 客户端第一次访问时，负载均衡会在返回请求中植入 Cookie（即在 HTTP 或 HTTPS 响应报文中插入 SERVERID），下次客户端携带此 Cookie 访问，负载均衡服务会将请求定向转发给之前记录到的后端服务器上。

    • Server：重写 Cookie。 负载均衡发现用户自定义了 Cookie，将会对原来的 Cookie 进行重写，下次客户端携带新的 Cookie 访问，负载均衡服务会将请求定向转发给之前记录到的后端服务器。

    说明

    当前服务器组 StickySessionEnabled 为 true 时，该参数生效。

    Insert
    ServerGroupId

    string

    是

    服务器组 ID。

    sgp-atstuj3rtop****
    UpstreamKeepaliveEnabled

    boolean

    否

    是否开启后端长连接。

    • true：开启

    • false：不开启。

    ServiceName

    string

    否

    仅适用于 ALB Ingress 场景，表示服务器组对应的K8s Service名称。

    test2
    UchConfig

    object

    否

    url 一致性 hash 参数配置。

    Type

    string

    是

    参数类型。只支持输入 QueryString。

    QueryString
    Value

    string

    是

    一致性 hash 参数值。

    abc
    ConnectionDrainConfig

    object

    否

    连接优雅中断相关配置。

    开启连接优雅中断，在移除后端服务器或者健康检查失败后，负载均衡使现有连接在一定时间内正常传输。

    说明

    • 基础版实例不支持开启连接优雅中断，仅标准版、WAF 增强版实例支持。

    • 服务器类型、IP 类型服务器组支持连接优雅中断，函数计算类型不支持。

    ConnectionDrainEnabled

    boolean

    否

    是否开启连接优雅中断。

    • true：开启

    • false：关闭

    false
    ConnectionDrainTimeout

    integer

    否

    连接优雅中断超时时间。

    取值范围：0~900。

    300
    SlowStartConfig

    object

    否

    慢启动相关配置。

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

    说明

    • 基础版实例不支持开启慢启动，仅标准版、WAF 增强版实例支持。

    • 服务器类型、IP 类型服务器组支持配置慢启动，函数计算类型不支持。

    • 慢启动仅在后端调度算法是加权轮询算法时可开启。

    SlowStartEnabled

    boolean

    否

    是否开启慢启动。

    • true：开启

    • false：关闭

    false
    SlowStartDuration

    integer

    否

    慢启动持续时间。

    取值范围：30~900。

    30
    CrossZoneEnabled

    boolean

    否

    服务器组是否开启跨 AZ 负载均衡。取值：

    • true：开启（默认值）

    • false：关闭

    说明

    • 基础版实例不支持绑定关闭跨 AZ 负载均衡的服务器组，仅标准版、WAF 增强版实例支持。

    • 服务器类型、IP 类型服务器组支持关闭跨 AZ 负载均衡，函数计算类型不支持。

    • 关闭跨 AZ 负载均衡时，不支持开启会话保持。

    true

    返回参数

    名称

    类型

    描述

    示例值

    object

    返回数据结构组

    JobId

    string

    异步任务 ID。

    72dcd26b-f12d-4c27-b3af-18f6aed5****
    RequestId

    string

    请求 ID。

    365F4154-92F6-4AE4-92F8-7FF3*****

    示例

    正常返回示例

    JSON格式

    {
  "JobId": "72dcd26b-f12d-4c27-b3af-18f6aed5****",
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF3*****"
}

    错误码

    HTTP status code

    错误码

    错误信息

    描述
    400 IncorrectStatus.ServerGroup The status of %s [%s] is incorrect. 服务器组状态无效。
    400 Mismatch.LoadBalancerEditionAndConnectionDrain The %s and %s are mismatched. 参数%s和%s不匹配。
    400 Mismatch.ServerGroupSchedulerAndSlowStartEnable The %s and %s are mismatched. 参数%s和%s不匹配。
    400 QuotaExceeded.ConnectionDrainTimeout The quota of %s is exceeded, usage %s/%s. 参数%s超过配额限制，当前值%s，配额值%s。
    400 UnsupportedFeature.ConnectionDrain The feature of %s is not supported. 不支持%s特性。
    400 QuotaExceeded.SlowStartDuration The quota of %s is exceeded, usage %s/%s. 参数%s超过配额限制，当前值%s，配额值%s。
    400 UnsupportedFeature.SlowStart The feature of %s is not supported. 不支持%s特性。
    400 Mismatch.LoadBalancerEditionAndSlowStartEnable The %s and %s are mismatched. 参数%s和%s不匹配。
    400 OperationDenied.UpstreamKeepaliveDisabled The operation is not allowed because of UpstreamKeepaliveDisabled. 不允许更新是否开启后端长连接为关闭状态
    400 OperationDenied.UpstreamKeepaliveEnabled The operation is not allowed because of UpstreamKeepaliveEnabled. 不允许更新是否开启后端长连接为开启状态
    400 CloseUpstreamKeepaliveNotSupport The param of UpstreamKeepalive is not Support. 不支持关闭服务器组的后端长链接
    404 ResourceNotFound.ServerGroup The specified resource %s is not found. 后端服务器组不存在。

    访问错误中心查看更多错误码。

    变更历史

    更多信息，参考变更详情。