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

Description

This operation can be called to modify the configurations such as protocol and ports of a listener to meet your business requirements.

When you call this operation, take note of the following items:

  • UpdateListener is an asynchronous operation. After you send a request, the system returns a request ID, but the operation is still being performed in the system background. You can call the DescribeListener operation to query the state of a listener.
    • If the listener is in the updating state, it indicates that its configurations are being modified. In this case, you can perform only query operations.
    • If the listener is in the active state, it indicates that its configurations are modified.
  • The UpdateListener operation cannot be repeatedly called to modify listener configurations for the same GA instance within a specific period of time.

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 make sure that it is unique among all requests. ClientToken can contain only ASCII characters.

Note If you do not set this parameter, ClientToken is set to the value of RequestId. The value of RequestId may be different for each API request.
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.

The description can be at most 200 characters in length.

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.
  • To enable client affinity, set this parameter to SOURCE_IP. In this case, when a client accesses stateful applications, requests from the same client are always 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 reserve client IP addresses. Default value: false. Valid values:

  • true: reserves client IP addresses. After client IP addresses are reserved, you can view the source IP addresses of clients over the backend service.
  • false: does not reserve client IP addresses.
Note This parameter will be discontinued in the API operations that are used to configure listeners. We recommend that you set this parameter when you call API operations to configure endpoint groups. For more information about the ProxyProtocol parameter, see CreateEndpointGroup and UpdateEndpointGroup.
PortRanges.N.FromPort Integer Yes 20

The start port of the listener port range that is used to receive and forward requests to endpoints.

Valid values: 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

The maximum number of ports that can be configured is subject to the routing type and protocol of the listener. For more information, see Listener overview.

Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the start port is the same as the end port.
PortRanges.N.ToPort Integer Yes 21

The end port of the listener port range that is used to receive and forward requests to endpoints.

Valid values: 1 to 65499. The FromPort value must be smaller than or equal to the ToPort value.

The maximum number of ports that can be configured is subject to the routing type and protocol of the listener. For more information, see Listener overview.

Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the start port is the same as the end port.
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 start port in the range of ports used by the backend server to receive requests.

Note This parameter is required only when you configure an HTTPS or HTTP listener and the listener port is different from the port over which the backend server provides services. In this case, the start port that is used to receive requests for the backend server must be the same as the end port.
BackendPorts.N.ToPort Integer No 80

The end port in the range of ports used by the backend server to receive requests.

Note This parameter is required only when you configure an HTTPS or HTTP listener and the listener port is different from the port over which the backend server provides services. In this case, the start port that is used to receive requests for the backend server must be the same as the end port.
XForwardedForConfig Object No

The configurations of the XForward headers.

XForwardedForGaIdEnabled Boolean No false

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

  • true: yes
  • false: no
Note You can specify this parameter only for HTTP and HTTPS listeners.
XForwardedForProtoEnabled Boolean No false

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

  • true: yes
  • false: no
Note You can specify this parameter only for HTTP and HTTPS listeners.
XForwardedForPortEnabled Boolean No false

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

  • true: yes
  • false: no
Note You can specify this parameter only for HTTP and HTTPS listeners.
XRealIpEnabled Boolean No false

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

  • true: yes
  • false: no
Note You can specify this parameter only for HTTP and HTTPS listeners.
XForwardedForGaApEnabled Boolean No false

Specifies whether to use the GA-AP header to retrieve the information about acceleration regions. Default value: false. Valid values:

  • true: yes
  • false: no
Note You can specify this parameter only for HTTP and HTTPS listeners.
SecurityPolicyId String No tls_cipher_policy_1_0

The ID of the security policy. Valid values:

  • tls_cipher_policy_1_0
    • Supported Transport Layer Security (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 You can specify this parameter only for HTTPS listeners.

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 listener port range is invalid.
400 PortConflict.Listener The listener port configuration is in conflict. The error message returned because the configuration of the specified listener port conflicts with that of another listener port.
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 GA instance does not exist.
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 no security policy ID is required for the listener.

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