Updates the configuration of a listener.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes UpdateListenerAttribute

The operation that you want to perform.

Set the value to UpdateListenerAttribute.

ListenerId String Yes lsr-bp1bpn0kn908w4nbw****

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

ClientToken String No 5A2CFF0E-5718-45B5-9D4D-70B3FF3898

The client token that is used to ensure the idempotency. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length.

DryRun Boolean No true

Specify whether to precheck this request. Valid values:

  • true: prechecks the API request. Resources are not created. The system checks the required parameters, request format and service limits. If the request fails the check, the corresponding error message is returned. If the request passes the precheck, the DryRunOperation error code is returned.
  • false (default): checks the request. After the request passes the check, an HTTP_2xx status code is returned and the operation is performed.
ListenerDescription String No test

The description of the listener.

The description must be 2 to 256 characters in length. The name can contain only the characters in the following string: /^([^\x00-\xff]|[\w.,;/@-]){2,256}$/.

RequestTimeout Integer No 3

Specifies the request timeout period. Unit: seconds. Valid values: 1 to 180.

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

IdleTimeout Integer No 15

Specify the timeout period of idle connections. Unit: seconds. Valid values: 1 to 60.

If no request is received within the specified timeout period, ALB closes the connection. ALB recreates the connection when a new connection request is received.

GzipEnabled Boolean No false

Specifies whether to enable gzip compression to compress files of a specific type.

Http2Enabled Boolean No false

Specifies whether to enable HTTP/2. Default value: on.

Valid values: true and false.

Note Only HTTPS listeners support this parameter.
SecurityPolicyId String No tls_cipher_policy_1_0

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

Note Only HTTPS listeners support this parameter.
XForwardedForConfig Object No

The configuration of XForwardFor.

XForwardedForClientCertClientVerifyAlias String No test_client-verify-alias_123456

The name of the custom header field. This parameter is valid only if XForwardedForClientCertClientVerifyEnabled is set to true.

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

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertClientVerifyEnabled Boolean No true

Specifies whether to use the X-Forwarded-Clientcert-clientverify header field to obtain the verification result of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintAlias String No test_finger-print-alias_123456

The name of the custom header field. This parameter is valid only if XForwardedForClientCertFingerprintEnabled is set to true.

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

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintEnabled Boolean No true

Specifies whether to use the X-Forwarded-Clientcert-fingerprint header field to obtain the fingerprint of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNAlias String No test_issue-dn-alias_123456

The name of the custom header field. This parameter is valid only if XForwardedForClientCertIssuerDNEnabled is set to On.

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

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNEnabled Boolean No true

Specifies whether to use the X-Forwarded-Clientcert-issuerdn header field to obtain information about the authority that issues the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNAlias String No test_subject-dn-alias_123456

The name of the custom header field. This parameter is valid only if XForwardedForClientCertSubjectDNEnabled is set to true.

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

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNEnabled Boolean No true

Specifies whether to use the X-Forwarded-Clientcert-subjectdn header field to obtain information about the owner of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientSrcPortEnabled Boolean No true

Specifies whether to use the X-Forwarded-Client-Port header field to obtain the port of the ALB client.

Valid values: true and false.

Default value: false.

Note HTTP and HTTPS listeners support this parameter.
XForwardedForEnabled Boolean No true

Specifies whether to use the X-Forwarded-For header to obtain the real IP address of the client.

Valid values: true and false.

Default value: true.

Note HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean No true

Specifies whether to use the X-Forwarded-Proto header to obtain the listener protocol of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBIdEnabled Boolean No true

Specifies whether to use the SLB-ID header field to obtain the ID of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBPortEnabled Boolean No true

Specifies whether to use the X-Forwarded-Port header field to obtain the listener port of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
QuicConfig Object No

The configuration information when you specify to associate QUIC listeners.

QuicListenerId String No lsn-333

The ID of the QUIC listener to be associated. If QuicUpgradeEnabled is set to true, this parameter is required. Only HTTPS listeners support this parameter.

Note The original listener and the QUIC listener must belong to the same ALB instance. In addition, make sure that the QUIC listener has not been associated before.
QuicUpgradeEnabled Boolean No true

Specify whether to enable the QUIC update feature.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
Certificates Array No

The certificates.

CertificateId String No 12315790212_166f8204689_1714763408_70998****

The certificate ID. You must enter IDs of server certificates.

DefaultActions Array No

The list of default actions.

ForwardGroupConfig Object No

The configuration of the forwarding action. If the Type parameter is set to FowardGroup, this parameter is required.

ServerGroupTuples Array No

The destination server groups to which requests are forwarded.

ServerGroupId String No rsp-cige6j5e7p****

The IDs of the destination server groups.

Type String No ForwardGroup

The action type.

Set the value to ForwardGroup. It indicates that requests are forwarded to multiple vServer groups.

Response parameters

Parameter Type Example Description
JobId String 72dcd26b-f12d-4c27-b3af-18f6aed5****

The ID of the query task.

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

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=UpdateListenerAttribute
&ListenerId=lsr-bp1bpn0kn908w4nbw****
&ClientToken=5A2CFF0E-5718-45B5-9D4D-70B3FF3898
&DryRun=true
&ListenerDescription=test
&RequestTimeout=3
&IdleTimeout=15
&GzipEnabled=false
&Http2Enabled=false
&SecurityPolicyId=tls_cipher_policy_1_0
&XForwardedForConfig={"XForwardedForClientCertClientVerifyAlias":"test_client-verify-alias_123456","XForwardedForClientCertClientVerifyEnabled":true,"XForwardedForClientCertFingerprintAlias":"test_finger-print-alias_123456","XForwardedForClientCertFingerprintEnabled":true,"XForwardedForClientCertIssuerDNAlias":"test_issue-dn-alias_123456","XForwardedForClientCertIssuerDNEnabled":true,"XForwardedForClientCertSubjectDNAlias":"test_subject-dn-alias_123456","XForwardedForClientCertSubjectDNEnabled":true,"XForwardedForClientSrcPortEnabled":true,"XForwardedForEnabled":true,"XForwardedForProtoEnabled":true,"XForwardedForSLBIdEnabled":true,"XForwardedForSLBPortEnabled":true}
&QuicConfig={"QuicListenerId":"lsn-333","QuicUpgradeEnabled":true}
&Certificates=[{"CertificateId":"12315790212_166f8204689_1714763408_70998****"}]
&DefaultActions=[{"ForwardGroupConfig":{"ServerGroupTuples":[{"ServerGroupId":"rsp-cige6j5e7p****"}]},"Type":"ForwardGroup"}]
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<UpdateListenerAttributeResponse>
    <JobId>72dcd26b-f12d-4c27-b3af-18f6aed5****</JobId>
    <RequestId>365F4154-92F6-4AE4-92F8-7FF34B540710</RequestId>
</UpdateListenerAttributeResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

HttpCode Error code Error message Description
400 IncorrectStatus.LoadBalancer The status of %s [%s] is incorrect. The error message returned because the status of the specified resource %s [%s] is invalid.
400 IncorrectBusinessStatus.LoadBalancer The business status of %s [%s] is incorrect. The error message returned because the business status of the specified resource %s [%s] is invalid.
400 IncorrectStatus.Listener The status of %s [%s] is incorrect. The error message returned because the status of the specified resource %s [%s] is invalid.
400 OperationDenied.CrossLoadBalancerQUICListener The operation is not allowed because of %s. The error message returned because the operation is not allowed because of %s.
400 ResourceAlreadyAssociated.Listener The specified resource %s is already associated. The error message returned because the specified resource %s is already associated.
400 OperationDenied.GRPCServerGroup The operation is not allowed because of %s. The error message returned because the operation is not allowed because of %s.
400 ResourceAlreadyAssociated.Certificate The specified resource %s is already associated. The error message returned because the specified resource %s is already associated.
400 ResourceQuotaExceeded.SecurityPolicyAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.ServerGroupAttachedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.LoadBalancerServersNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 ResourceQuotaExceeded.ServerAddedNum The quota of %s is exceeded for resource %s, usage %s/%s. The error message returned because the usage %s has reached the upper limit %s of the specified resource %s.
400 OperationDenied.ServerGroupProtocolNotSupport The operation is not allowed because of ServerGroupProtocolNotSupport. The error message returned because the specified server group protocol is invalid.
404 ResourceNotFound.Listener The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.ServerGroup The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.SecurityPolicy The specified resource %s is not found. The error message returned because the specified resource %s does not exist.
404 ResourceNotFound.Certificate The specified resource %s is not found. The error message returned because the specified resource %s does not exist.

For a list of error codes, visit the API Error Center.