全部產品
Search

搜尋本產品

    Server Load Balancer：UpdateListenerAttribute

    文件中心

    Server Load Balancer：UpdateListenerAttribute

    更新時間：Sep 02, 2026

    更新監聽器的設定，例如名稱、預設動作等。

    介面說明

    UpdateListenerAttribute 介面屬於非同步介面，即系統返回一個請求 ID，但該監聽器的設定尚未更新成功，系統背景的更新任務仍在進行。您可以呼叫 GetListenerAttribute 查詢監聽器設定的更新狀態：

    • 當監聽器處於 Configuring 狀態時，表示監聽器的設定正在更新中。

    • 當監聽器處於 Running 狀態時，表示監聽器的設定更新成功。

    調試

    您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

    調試

    授權資訊

    下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

    • 操作：是指具體的許可權點。

    • 存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。

    • 資源類型：是指操作中支援授權的資源類型。具體說明如下：

      • 對於必選的資源類型，用前面加 * 表示。

      • 對於不支援資源級授權的操作，用全部資源表示。

    • 條件關鍵字：是指雲產品自身定義的條件關鍵字。

    • 關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    alb:UpdateListenerAttribute

    update

    *LoadBalancer

    acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

    *SecurityPolicy

    acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}

    *ServerGroup

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

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    ListenerId

    string

    是

    應用程式負載平衡執行個體監聽器 ID。

    lsn-o4u54y73wq7b******
    ClientToken

    string

    否

    用戶端 Token，用於保證請求的冪等性。

    從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 僅支援 ASCII 字元。

    說明

    若您未指定，則系統自動使用 API 請求的 RequestId 作為 ClientToken 識別碼。每次 API 請求的 RequestId 都不一樣。

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

    boolean

    否

    是否僅預檢此次請求。取值：

    • true：傳送檢查請求，不會更新監聽器的設定。檢查項目包括是否填寫了必要參數、請求格式、業務限制。如果檢查不通過，則返回對應錯誤。如果檢查通過，則返回錯誤碼 DryRunOperation。

    • false（預設值）：傳送正常請求，通過檢查後返回 HTTP 2xx 狀態碼並直接進行操作。

    false
    ListenerDescription

    string

    否

    自訂監聽器名稱。

    長度為 2~256 個字元，可包含英文字母、數字、中文、半形逗號（,）、半形句號（.）、半形分號（;）、正斜線（/）、at（@）、底線（_）和連字號（-）。

    HTTP_80
    RequestTimeout

    integer

    否

    指定請求逾時時間。單位：秒。取值範圍：1~600。

    如果在逾時時間內後端伺服器一直沒有回應，負載平衡將放棄等待，向用戶端返回 HTTP 504 錯誤碼。

    60
    IdleTimeout

    integer

    否

    指定連線閒置逾時時間。單位：秒。取值範圍：1~600。

    如果在逾時時間內一直沒有存取請求，負載平衡會暫時中斷目前連線，直到下一次請求來臨時重新建立新的連線。

    15
    GzipEnabled

    boolean

    否

    是否啟用 Gzip 壓縮，對特定檔案類型進行壓縮。取值：

    • true：是。

    • false：否。

    true
    Http2Enabled

    boolean

    否

    是否啟用 HTTP/2 特性。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器支援此參數。

    true
    SecurityPolicyId

    string

    否

    安全性原則，支援系統安全性原則和自訂安全性原則。

    說明

    僅 HTTPS 監聽器支援此參數。

    tls_cipher_policy_1_0
    CaEnabled

    boolean

    否

    是否啟用雙向驗證。取值：

    • true：是。

    • false：否。

    false
    XForwardedForConfig

    object

    否

    XForwardedFor 相關屬性設定。

    XForwardedForClientCertClientVerifyAlias

    string

    否

    自訂標頭欄位名稱，只有當 XForwardedForClientCertClientVerifyEnabled 的值為 true 時，此值才會生效。

    取值限制：長度 1~40 個字元。支援字母 a~z、連字號（-）、底線（_）和數字。

    說明

    僅 HTTPS 監聽器支援此參數。

    test_client-verify-alias_123456
    XForwardedForClientCertClientVerifyEnabled

    boolean

    否

    是否透過 X-Forwarded-Clientcert-clientverify 標頭欄位取得存取負載平衡執行個體用戶端憑證的驗證結果。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器支援此參數。

    false
    XForwardedForClientCertFingerprintAlias

    string

    否

    自訂標頭欄位名稱，只有當 XForwardedForClientCertFingerprintEnabled 的值為 true 時才生效。

    取值限制：長度為 1~40 個字元。支援字母 a~z、連字號（-）、底線（_）和數字。

    說明

    僅 HTTPS 監聽器支援此參數。

    test_finger-print-alias_123456
    XForwardedForClientCertFingerprintEnabled

    boolean

    否

    是否透過 X-Forwarded-Clientcert-fingerprint 標頭欄位取得存取負載平衡執行個體用戶端憑證的指紋取值。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器支援此參數。

    false
    XForwardedForClientCertIssuerDNAlias

    string

    否

    自訂標頭欄位名稱，只有當 XForwardedForClientCertIssuerDNEnabled 的值為 true 時才生效。

    取值限制：長度為 1~40 個字元。支援字母 a~z、連字號（-）、底線（_）和數字。

    說明

    僅 HTTPS 監聽器支援此參數。

    test_issue-dn-alias_123456
    XForwardedForClientCertIssuerDNEnabled

    boolean

    否

    是否透過 X-Forwarded-Clientcert-issuerdn 標頭欄位取得存取負載平衡執行個體用戶端憑證的發行者資訊。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器支援此參數。

    false
    XForwardedForClientCertSubjectDNAlias

    string

    否

    自訂標頭欄位名稱，只有當 XForwardedForClientCertSubjectDNEnabled 的值為 true 時才生效。

    取值限制：長度為 1~40 個字元。支援字母 a~z、連字號（-）、底線（_）和數字。

    說明

    僅 HTTPS 監聽器支援此參數。

    test_subject-dn-alias_123456
    XForwardedForClientCertSubjectDNEnabled

    boolean

    否

    是否透過 X-Forwarded-Clientcert-subjectdn 標頭欄位取得存取負載平衡執行個體用戶端憑證的所有者資訊。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器支援此參數。

    false
    XForwardedForClientSrcPortEnabled

    boolean

    否

    是否透過 X-Forwarded-Client-srcport 標頭欄位取得存取負載平衡執行個體用戶端的連接埠。取值：

    • true：是。

    • false：否。

    說明

    HTTP 和 HTTPS 監聽器支援此參數。

    false
    XForwardedForEnabled

    boolean

    否

    是否透過 X-Forwarded-For 標頭欄位取得訪客真實 IP。取值：

    • true（預設值）：是。

    • false：否。

    說明

    1. 設定 true，XForwardedForProcessingMode 預設取值 append，支援修改為 remove。

    2. 設定 false，將請求傳送至後端服務之前保留 X-Forwarded-For 標頭欄位，不做額外處理。

    3. HTTP 和 HTTPS 監聽器支援此參數。

    true
    XForwardedForProcessingMode

    string

    否

    處理 X-Forwarded-For 標頭欄位的模式。只有當 XForwardedForEnabled 為 true 時，此值才會生效。取值：

    • append（預設值）：附加。

    • remove：刪除。

    說明

    1. 設定 append，將請求傳送至後端服務之前把最後一跳 IP 加入 X-Forwarded-For 標頭欄位。

    2. 設定 remove，將請求傳送至後端服務之前刪除 X-Forwarded-For 標頭，無論請求是否攜帶 X-Forwarded-For 標頭欄位。

    3. HTTP 和 HTTPS 監聽器支援此參數。

    append
    XForwardedForProtoEnabled

    boolean

    否

    是否透過 X-Forwarded-Proto 標頭欄位取得負載平衡執行個體的監聽器通訊協定。取值：

    • true：是。

    • false：否。

    說明

    HTTP、HTTPS 和 QUIC 監聽器支援此參數。

    false
    XForwardedForSLBIdEnabled

    boolean

    否

    是否透過 SLB-ID 標頭欄位取得負載平衡執行個體 ID。取值：

    • true：是。

    • false：否。

    說明

    HTTP、HTTPS 和 QUIC 監聽器支援此參數。

    false
    XForwardedForSLBPortEnabled

    boolean

    否

    是否透過 X-Forwarded-Port 標頭欄位取得負載平衡執行個體的監聽器連接埠。取值：

    • true：是。

    • false：否。

    說明

    HTTP、HTTPS 和 QUIC 監聽器支援此參數。

    false
    XForwardedForClientSourceIpsEnabled

    boolean

    否

    是否允許 ALB 從 X-Forwarded-For 標頭欄位中尋找真實用戶端 IP。取值：

    • true：是。

    • false：否。

    說明

    HTTP、HTTPS 監聽器支援此參數。

    false
    XForwardedForClientSourceIpsTrusted

    string

    否

    指定可信的代理 IP。

    應用程式負載平衡 ALB 會從後往前遍歷 X-Forwarded-For，選取第一個不在可信 IP 清單中的 IP 作為真實的用戶端 IP，該 IP 會被用於來源 IP 限速。

    10.1.1.0/24
    XForwardedForHostEnabled

    boolean

    否

    是否啟用透過 X-Forwarded-Host 標頭欄位取得存取負載平衡執行個體用戶端的網域名稱。取值：

    • true：是。

    • false（預設值）：否。

    說明

    HTTP、HTTPS 和 QUIC 監聽器支援此參數。

    false
    QuicConfig

    object

    否

    啟用關聯 QUIC 監聽器時的設定資訊。

    QuicListenerId

    string

    否

    需要關聯的 QUIC 監聽器 ID。QuicUpgradeEnabled 值為 true 時必選。HTTPS 監聽器時有效。

    說明

    原始監聽器和關聯的 QUIC 監聽器必須屬於同一個 ALB 執行個體，並且此 QUIC 監聽器之前沒有被關聯過。

    lsn-333
    QuicUpgradeEnabled

    boolean

    否

    是否啟用 QUIC 升級。取值：

    • true：是。

    • false：否。

    說明

    僅 HTTPS 監聽器時有效。

    false
    Certificates

    array<object>

    否

    憑證清單。

    object

    否

    憑證結構。

    CertificateId

    string

    否

    預設憑證 ID，目前僅支援新增 1 個預設伺服器憑證。

    說明

    123157******
    CaCertificates

    array<object>

    否

    CA 憑證清單。目前僅支援新增 1 個 CA 憑證。

    object

    否

    CA 憑證結構。

    CertificateId

    string

    否

    CA 憑證 ID。

    說明

    當 CaEnabled 參數取值為 true 時，此參數為必填。

    123359******
    DefaultActions

    array<object>

    否

    預設規則動作清單。

    array<object>

    否

    預設規則動作結構。

    ForwardGroupConfig

    object

    否

    轉發動作對應的設定，當 Type 類型為 ForwardGroup 時必填且有效。最多支援新增 20 個轉發動作對應的設定。

    ServerGroupTuples

    array<object>

    是

    轉發目標伺服器元組清單。

    object

    否

    轉發目標伺服器元組結構。

    ServerGroupId

    string

    是

    轉發到的目的伺服器群組 ID。

    sgp-i5qt20******
    Type

    string

    是

    動作類型。最多支援新增 1 個動作類型。

    取值：ForwardGroup，表示轉發至多個伺服器群組。

    ForwardGroup

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    返回資料結構體。

    JobId

    string

    非同步任務 ID。

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

    string

    請求 ID。

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

    樣本

    正常返回樣本

    JSON格式

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

    錯誤碼

    HTTP status code

    錯誤碼

    錯誤資訊

    描述
    400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect. 執行個體的目前狀態不支援本次操作。
    400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s]  is incorrect. 執行個體的目前狀態不支援本次操作。
    400 IncorrectStatus.Listener The status of %s [%s] is incorrect. 監聽器的目前狀態不支援本次操作。
    400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. 操作被拒絕，原因為%s。
    400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. 資源 %s 已被關聯。
    400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s. 操作被拒絕，原因是存在綁定此 gRPC 伺服器群組的監聽器未啟用 HTTP/2.0。
    400 ResourceAlreadyAssociated.Certificate The specified resource %s is already associated. 憑證已被關聯。
    400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 配額%s已超出額度限制，資源為%s，目前已使用%s，配額為%s。
    400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. 伺服器群組可被關聯數已超過額度限制。
    400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. 後端伺服器數已超過額度限制。
    400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. 伺服器新增至群組已超過額度限制。
    400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. 操作被拒絕，原因是 ServerGroupProtocolNotSupport。
    400 UnsupportedFeature.FullTraceHttps The feature of FullTraceHttps is not supported for current instance. 目前執行個體版本不支援全鏈路HTTPS特性。
    400 ResourceInConfiguring.Listener The specified resource of %s is being configured, please try again later. 指定的資源 %s 正在設定中，請稍後再試。
    400 Mismatch.VpcId The %s is mismatched for %s and %s. %s 在 %s 和 %s 中不匹配。
    400 InvalidParameter Invalid parameter, please check the parameter input. 無效參數，請檢查參數輸入。
    400 OperationDenied.CACertificateCorrupted The CA certificate is corrupted. CA 憑證已損毀。
    403 Forbidden.LoadBalancer Authentication is failed for %s. 負載平衡操作驗證失敗。
    404 ResourceNotFound.Listener The specified resource %s is not found. 監聽器不存在。
    404 ResourceNotFound.ServerGroup The specified resource %s is not found. 後端伺服器群組不存在。
    404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. 資源%s不存在。
    404 ResourceNotFound.Certificate The specified resource %s is not found. 指定的憑證不存在。

    訪問錯誤中心查看更多錯誤碼。

    變更歷史

    更多資訊，參考變更詳情。