All Products
Search

This Product

    Server Load Balancer:UpdateListenerAttribute

    Document Center

    Server Load Balancer:UpdateListenerAttribute

    Last Updated:Mar 01, 2024

    Updates the attributes of a listener, such as the name and the default action.

    Operation description

    UpdateListenerAttribute is an asynchronous operation. After a request is sent, the system returns a request ID and runs the task in the background. You can call the GetListenerAttribute operation to query the status of the task.

    • If a listener is in the Configuring state, the configuration of the listener is being modified.
    • If a listener is in the Running state, the configuration of the listener is modified.

    Debugging

    OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    alb:UpdateListenerAttributeWrite
    • LoadBalancer
      acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}
    • SecurityPolicy
      acs:alb:{#regionId}:{#accountId}:securitypolicy/{#securitypolicyId}
    • ServerGroup
      acs:alb:{#regionId}:{#accountId}:servergroup/{#servergroupId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    ListenerIdstringYes

    The ID of the Application Load Balancer (ALB) listener.

    		lsr-bp1bpn0kn908w4nbw****
    ClientTokenstringNo

    The client token that is used to ensure the idempotence of the request.

    You can use the client to generate the token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters.

    Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.
    		5A2CFF0E-5718-45B5-9D4D-70B3FF3898
    DryRunbooleanNo

    Specifies whether to perform only a dry run, without performing the actual request. Valid values:

    • true: performs only a dry run. The system checks the request for potential issues, including missing parameter values, incorrect request syntax, and service limits. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
    • false (default): performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
    		false
    ListenerDescriptionstringNo

    The name of the listener.

    The name must be 2 to 256 characters in length, and can contain letters, digits, and the following special characters: , . ; / @ _ -.

    		HTTP_80
    RequestTimeoutintegerNo

    The timeout period of a request. Unit: seconds. Valid values: 1 to 180.

    If no response is received from the backend server within the specified timeout period, ALB returns an HTTP 504 error code to the client.

    		3
    IdleTimeoutintegerNo

    The timeout period of an idle connection. Unit: seconds. Valid values: 1 to 60.

    If no request is received within the specified timeout period, ALB closes the current connection. When another request is received, ALB establishes a new connection.

    		15
    GzipEnabledbooleanNo

    Specifies whether to enable GZIP compression for specific types of files. Valid values:

    • true
    • false
    		true
    Http2EnabledbooleanNo

    Specifies whether to enable HTTP/2. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTPS listener.
    		true
    SecurityPolicyIdstringNo

    The security policy ID. System security policies and custom security policies are supported.

    Note This parameter is available only when you create an HTTPS listener.
    		tls_cipher_policy_1_0
    CaEnabledbooleanNo

    Specifies whether to enable mutual authentication. Valid values:

    • true
    • false
    		false
    XForwardedForConfigobjectNo

    The configuration of the XForwardFor headers.

    XForwardedForClientCertClientVerifyAliasstringNo

    The name of the custom header. This parameter takes effect only when the XForwardedForClientCertClientVerifyEnabled parameter is set to true.

    The name must be 1 to 40 characters in length, and can contain letters, hyphens (-), underscores (_), and digits.

    Note This parameter is available only when you create an HTTPS listener.
    		test_client-verify-alias_123456
    XForwardedForClientCertClientVerifyEnabledbooleanNo

    Specifies whether to use the X-Forwarded-Clientcert-clientverify header to retrieve the verification result of the client certificate. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTPS listener.
    		false
    XForwardedForClientCertFingerprintAliasstringNo

    The name of the custom header. This parameter takes effect only when the XForwardedForClientCertFingerprintEnabled parameter is set to true.

    The name must be 1 to 40 characters in length, and can contain letters, hyphens (-), underscores (_), and digits.

    Note This parameter is available only when you create an HTTPS listener.
    		test_finger-print-alias_123456
    XForwardedForClientCertFingerprintEnabledbooleanNo

    Indicates whether the X-Forwarded-Clientcert-fingerprint header is used to retrieve the fingerprint of the client certificate. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTPS listener.
    		false
    XForwardedForClientCertIssuerDNAliasstringNo

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true.

    The name must be 1 to 40 characters in length, and can contain letters, hyphens (-), underscores (_), and digits.

    Note This parameter is available only when you create an HTTPS listener.
    		test_issue-dn-alias_123456
    XForwardedForClientCertIssuerDNEnabledbooleanNo

    Indicates whether the X-Forwarded-Clientcert-issuerdn header is used to retrieve information about the authority that issues the client certificate. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTPS listener.
    		false
    XForwardedForClientCertSubjectDNAliasstringNo

    The name of the custom header. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true.

    The name must be 1 to 40 characters in length, and can contain letters, hyphens (-), underscores (_), and digits.

    Note This parameter is available only when you create an HTTPS listener.
    		test_subject-dn-alias_123456
    XForwardedForClientCertSubjectDNEnabledbooleanNo

    Indicates whether the X-Forwarded-Clientcert-subjectdn header is used to retrieve information about the owner of the client certificate. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTPS listener.
    		false
    XForwardedForClientSrcPortEnabledbooleanNo

    Indicates whether the X-Forwarded-Client-Port header is used to retrieve the client port. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTP or HTTPS listener.
    		false
    XForwardedForEnabledbooleanNo

    Indicates whether the X-Forwarded-For header is used to retrieve the client IP address. Valid values:

    • true
    • false
    Note This parameter is available only when you create an HTTP or HTTPS listener.
    		true
    XForwardedForProtoEnabledbooleanNo

    Specifies whether to use the X-Forwarded-Proto header to retrieve the listener protocol of the ALB instance. Valid values:

    • true
    • false
    Note HTTP, HTTPS, and QUIC listeners support this parameter.
    		false
    XForwardedForSLBIdEnabledbooleanNo

    Specifies whether to use the SLB-ID header to retrieve the ID of the ALB instance. Valid values:

    • true
    • false
    Note HTTP, HTTPS, and QUIC listeners support this parameter.
    		false
    XForwardedForSLBPortEnabledbooleanNo

    Specifies whether to use the X-Forwarded-Port header to retrieve the listening port. Valid values:

    • true
    • false
    Note HTTP, HTTPS, and QUIC listeners support this parameter.
    		false
    XForwardedForClientSourceIpsEnabledbooleanNo

    Specifies whether to use the X-Forwarded-Client-Ip header to retrieve the source IP addresses. Valid values:

    • true
    • false
    Note HTTP, HTTPS, and QUIC listeners support this parameter. By default, the feature that corresponds to this parameter is unavailable. If you want to use this feature, contact your account manager.
    		false
    XForwardedForClientSourceIpsTrustedstringNo

    The trusted proxy IP address.

    ALB traverses X-Forwarded-For backward and selects the first IP address that is not in the trusted IP address list as the real IP address of the client. The IP address is used in source IP address throttling.

    		10.1.1.0/24
    QuicConfigobjectNo

    The configuration information when the listener is associated with a QUIC listener.

    QuicListenerIdstringNo

    The QUIC listener ID. This parameter is required if QuicUpgradeEnabled is set to true. Only HTTPS listeners support this parameter.

    Note You must add the HTTPS listener and the QUIC listener to the same ALB instance. In addition, make sure that the QUIC listener has never been associated with another listener.
    		lsn-333
    QuicUpgradeEnabledbooleanNo

    Specifies whether to enable QUIC upgrade. Valid values:

    • true
    • false
    Note Only HTTPS listeners support this parameter.
    		false
    Certificatesobject []No

    The certificates.

    CertificateIdstringNo

    The certificate ID. Only server certificates are supported. You can specify up to 20 certificate IDs.

    		12315790212_166f8204689_1714763408_70998****
    CaCertificatesobject []No

    The certificate authority (CA) certificates.

    DefaultActionsobject []No

    The default actions in the forwarding rules.

    ForwardGroupConfigobjectNo

    The configuration of the action. This parameter is required and takes effect when the Type parameter is set to FowardGroup. You can specify configurations for up to 20 forwarding actions.

    ServerGroupTuplesobject []Yes

    The server groups to which requests are forwarded.

    ServerGroupIdstringYes

    The server group to which requests are forwarded.

    		rsp-cige6j5e7p****
    TypestringYes

    The type of the action. You can specify only one action type.

    Set the value to ForwardGroup to forward requests to multiple vServer groups.

    		ForwardGroup

    Response parameters

    ParameterTypeDescriptionExample
    object

    The response parameters.

    JobIdstring

    The asynchronous task ID.

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

    The request ID.

    		365F4154-92F6-4AE4-92F8-7FF34B540710

    Examples

    Sample success responses

    JSONformat

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

    Error codes

    HTTP status codeError codeError messageDescription
    400IncorrectStatus.LoadBalancerThe status of %s [%s] is incorrect.The status of %s [%s] is incorrect.
    400IncorrectBusinessStatus.LoadBalancerThe business status of %s [%s]  is incorrect.The business status of %s [%s]  is incorrect.
    400IncorrectStatus.ListenerThe status of %s [%s] is incorrect.The status of %s [%s] is incorrect.
    400MisMatch.VpcIdThe %s is mismatched for %s and %s.The %s is mismatched for %s and %s.
    400OperationDenied.CrossLoadBalancerQUICListenerThe operation is not allowed because of %s.The operation is not allowed because of %s.
    400ResourceAlreadyAssociated.ListenerThe specified resource %s is already associated.The specified resource %s is already associated.
    400OperationDenied.GRPCServerGroupThe operation is not allowed because of %s.The operation is not allowed because of %s.
    400ResourceAlreadyAssociated.CertificateThe specified resource %s is already associated.The specified resource %s is already associated.
    400ResourceQuotaExceeded.SecurityPolicyAttachedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
    400ResourceQuotaExceeded.ServerGroupAttachedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s, usage %s/%s.
    400ResourceQuotaExceeded.LoadBalancerServersNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
    400ResourceQuotaExceeded.ServerAddedNumThe quota of %s is exceeded for resource %s, usage %s/%s.The quota of %s is exceeded for resource %s. Usage: %s/%s.
    400ResourceInConfiguring.ListenerThe specified resource %s is being configured. Please try again later.-
    400OperationDenied.ServerGroupProtocolNotSupportThe operation is not allowed because of ServerGroupProtocolNotSupport.The operation is not allowed because the server group protocol is not supported.
    400UnsupportedFeature.FullTraceHttpsThe feature of FullTraceHttps is not supported for current instance.-
    404ResourceNotFound.ListenerThe specified resource %s is not found.The specified resource %s is not found.
    404ResourceNotFound.ServerGroupThe specified resource %s is not found.The specified resource %s is not found.
    404ResourceNotFound.SecurityPolicyThe specified resource %s is not found.The specified resource %s is not found.
    404ResourceNotFound.CertificateThe specified resource %s is not found.The specified resource %s is not found.

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-01-29The Error code has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      Error Codes 400 change
      delete Error Codes: 403
      delete Error Codes: 404
    2024-01-24The Error code has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      Error Codes 400 change
      delete Error Codes: 404
      Added Error Codes: 403
    2023-11-06The Error code has changedsee changesets
    Change itemChange content
    Error CodesThe Error code has changed.
      delete Error Codes: 400
      delete Error Codes: 404