Modifies the configurations of a specified listener of a Global Accelerator (GA) instance.

Description

This API operation is used to modify the protocol, port, and endpoint group of a specified listener to meet your business requirements.

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 UpdateListener

The operation that you want to perform. Set the value to UpdateListener.

RegionId String No cn-hangzhou

The ID of the region where the GA instance is deployed. Set the value to cn-hangzhou.

ClientToken String No 123e4567-e89b-12d3-a456-426655440000

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

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.

Name String No Listener

The name of the listener.

The name must be 2 to 128 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter.

Description String No Listener

The description of the listener.

ClientAffinity String No SOURCE_IP

Specifies whether to enable client affinity for the listener.

  • If this parameter is left empty, client affinity is disabled. After client affinity is disabled, requests from a specific client IP address may be forwarded to different endpoints.
  • If this parameter is set to SOURCE_IP, client affinity is enabled. In this case, when a client accesses stateful applications, requests from the same client are forwarded to the same endpoint regardless of the source port or protocol.
Protocol String No tcp

The network transmission protocol that is used by the listener. Valid values:

  • tcp: TCP
  • udp: UDP
  • http: HTTP
  • https: HTTPS
ListenerId String Yes lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

ProxyProtocol String No false

Specifies whether to preserve client IP addresses. Valid values:

  • true: preserves client IP addresses. After this feature is enabled, backend servers can retrieve client IP addresses.
  • false (default): does not preserve client IP addresses.
XForwardedForConfig Object No

The configuration of the XForward field.

XForwardedForGaIdEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForPortEnabled Boolean No false

Specifies whether to use the GA-X-Forward-Port header to retrieve the listener ports of the GA instance. Valid values:

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XRealIpEnabled Boolean No false

Specifies whether to use the X-Real-IP header to retrieve client IP addresses. Valid values:

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForGaApEnabled Boolean No false

Specifies whether to use the GA-AP header to retrieve the information about the acceleration area. Valid values:

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
SecurityPolicyId String No tls_cipher_policy_1_0

The ID of the security policy. Valid values:

  • tls_cipher_policy_1_0
    • Supported TLS versions: TLS 1.0, TLS 1.1, and TLS 1.2.
    • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.
  • tls_cipher_policy_1_1
    • Supported TLS versions: TLS 1.1 and TLS 1.2.
    • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.
  • tls_cipher_policy_1_2
    • Supported TLS version: TLS 1.2.
    • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, AES128-GCM-SHA256, AES256-GCM-SHA384, AES128-SHA256, AES256-SHA256, ECDHE-RSA-AES128-SHA, ECDHE-RSA-AES256-SHA, AES128-SHA, AES256-SHA, and DES-CBC3-SHA.
  • tls_cipher_policy_1_2_strict
    • Supported TLS version: TLS 1.2.
    • Supported cipher suites: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.
  • tls_cipher_policy_1_2_strict_with_1_3
    • Supported TLS versions: TLS 1.2 and TLS 1.3.
    • Supported cipher suites: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, TLS_AES_128_CCM_8_SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES128-SHA256, ECDHE-ECDSA-AES256-SHA384, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, ECDHE-ECDSA-AES128-SHA, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES128-SHA, and ECDHE-RSA-AES256-SHA.
Note Only HTTPS listeners support this parameter.
PortRanges.N.FromPort Integer Yes 20

The starting listener port that is used to receive and forward requests to endpoints.

Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the starting and ending listener ports are the same.
PortRanges.N.ToPort Integer Yes 21

The ending listener port that is used to receive and forward requests to endpoints.

Certificates.N.Id String No 449****-cn-hangzhou

The ID of the SSL certificate.

Note This parameter is required only when you configure an HTTPS listener.
BackendPorts.N.FromPort Integer No 80

The starting port that is used by the backend server to receive requests.

Note This parameter is required only when you configure an HTTPS listener and the listener port is the same port used by the backend server to provide services. When you use an HTTPS listener, the starting port that is used to receive requests for the backend server must be the same as the ending port.
BackendPorts.N.ToPort Integer No 80

The ending port that is used by the backend server to receive requests.

Response parameters

Parameter Type Example Description
RequestId String 6FEA0CF3-D3B9-43E5-A304-D217037876A8

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=UpdateListener
&RegionId=cn-hangzhou
&ClientToken=123e4567-e89b-12d3-a456-426655440000    
&Name=Listener
&Description=Listener
&ClientAffinity=SOURCE_IP
&Protocol=tcp
&ListenerId=lsr-bp1bpn0kn908w4nbw****
&ProxyProtocol=false
&PortRanges=[{"FromPort":20,"ToPort":21}]
&Certificates=[{"Id":"449****-cn-hangzhou"}]
&BackendPorts=[{"FromPort":80,"ToPort":80}]
&XForwardedForConfig={"XForwardedForGaIdEnabled":false,"XForwardedForProtoEnabled":false,"XForwardedForPortEnabled":false,"XRealIpEnabled":false,"XForwardedForGaApEnabled":false}
&SecurityPolicyId=tls_cipher_policy_1_0
&Common request parameters

Sample success responses

XML format

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

<UpdateListenerResponse>
    <RequestId>6FEA0CF3-D3B9-43E5-A304-D217037876A8    </RequestId>
</UpdateListenerResponse>

JSON format

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

{
  "RequestId" : "6FEA0CF3-D3B9-43E5-A304-D217037876A8\t"
}

Error codes

HttpCode Error code Error message Description
400 NotActive.Listener The state of the listener is not active. The error message returned because the specified listener is unstable.
400 PortRangeIllegal.Listener The specified listener port range is invalid. The error message returned because the specified port range is invalid.
400 PortConflict.Listener The listener port configuration is in conflict. The error message returned because the specified listener port is already used.
400 QuotaExceeded.ListenerPort The maximum number of listener ports is exceeded. The error message returned because the number of listener ports has reached the upper limit.
400 NotExist.Accelerator The accelerated instance does not exist. The error message returned because the specified GA instance does not exist.
400 StateError.Accelerator The state of the accelerated instance is invalid. The error message returned because the specified GA instance is in an invalid state.
400 PortRanges.MustOne The portRanges must be one for HTTPS and HTTP type listener. The error message returned because an HTTP or HTTPS listener supports only one port.
400 SecurityPolicyIdIllegal.Listener The listener security policy ID %s is illegal. The error message returned because the security policy ID of the listener is invalid.
400 SecurityPolicyId.NotNeed No security policy ID is required for the listener. The error message returned because you do not need to configure the security policy ID for the specified listener.

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