Modify GA Listener Settings via UpdateListener API - Global Accelerator - Alibaba Cloud - Global Accelerator

Invokes the UpdateListener operation to modify the configuration of a specified listener for an Alibaba Cloud Global Accelerator (GA) instance.

Operation description

This operation modifies the protocol, port, and other settings of a specified listener to meet your business requirements.

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

UpdateListener is an asynchronous operation. After a request is sent, the system returns a request ID, but the listener configuration has not been modified yet. The modification node is still running in the background. You can invoke DescribeListener to query the status of the listener:
- If the listener is in the updating state, the listener configuration is being modified. In this state, you can only execute query operations.
- If the listener is in the active state, the listener configuration has been modified.
UpdateListener does not support concurrent modification of listener configurations within the same Alibaba Cloud Global Accelerator (GA) instance.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ga:UpdateListener

update

*Listener

acs:ga:{#regionId}:{#accountId}:listener/{#listenerId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	No	The region ID of the Alibaba Cloud Global Accelerator (GA) instance. Set the value to cn-hangzhou.	cn-hangzhou
ClientToken	string	No	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 client token can contain only ASCII characters. Note If you do not specify this parameter, the system automatically uses the RequestId of the API request as the ClientToken. The RequestId may be different for each API request.	123e4567-e89b-12d3-a456-426655440000
Name	string	No	The name of the listener. The name must be 1 to 128 characters in length and can contain letters, digits, periods (.), underscores (_), and hyphens (-). It must start with a letter or a Chinese character.	Listener
Description	string	No	The description of the listener. The description can be up to 200 characters in length and cannot start with `http://` or `https://`.	Listener
ClientAffinity	string	No	The client affinity. Valid values: NONE: Client affinity is not maintained. Requests from the same client may not always be directed to the same endpoint. SOURCE_IP: Client affinity is maintained. When a client accesses a stateful application, all requests from the same client can be directed to the same endpoint, regardless of the source port and protocol.	SOURCE_IP
Protocol	string	No	The network transmission protocol type of the listener. Valid values: tcp: TCP. udp: UDP. http: HTTP. https: HTTPS.	tcp
ListenerId	string	Yes	The listener instance ID.	lsr-bp1bpn0kn908w4nbw****
ProxyProtocol `deprecated`	string	No	Specifies whether to preserve client IP addresses. Valid values: true: Client IP addresses are preserved. After this feature is enabled, backend services can view the originating IP addresses of clients. false (default): Client IP addresses are not preserved. Note This parameter will no longer be configured in listener API operations. Configure this parameter in the endpoint group API operations. For more information about ProxyProtocol, see CreateEndpointGroup and UpdateEndpointGroup.	false
PortRanges	array<object>	No	The port range that is used to receive requests and forward them to endpoints. Valid values of listener ports: 1 to 65499. The maximum number of ports that can be configured varies based on the listener routing type and listener protocol type. For more information, see Listener ports.
	object	No	The port range that is used to receive requests and forward them to endpoints. Valid values of listener ports: 1 to 65499. The maximum number of ports that can be configured varies based on the listener routing type and listener protocol type. For more information, see Listener ports.
FromPort	integer	Yes	The first port in the range of listener ports that are used to receive and forward requests to endpoints. Valid values of listener ports: 1 to 65499. The value of FromPort must be less than or equal to the value of ToPort. The maximum number of ports that can be configured varies based on the listener routing type and listener protocol type. For more information, see Listener ports. Note For HTTP or HTTPS listeners, only one listener port can be configured. The first port must be the same as the last port.	20
ToPort	integer	Yes	The last port in the range of listener ports that are used to receive and forward requests to endpoints. Valid values of listener ports: 1 to 65499. The value of FromPort must be less than or equal to the value of ToPort. The maximum number of ports that can be configured varies based on the listener routing type and listener protocol type. For more information, see Listener ports. Note For HTTP or HTTPS listeners, only one listener port can be configured. The first port must be the same as the last port.	21
Certificates	array<object>	No	The SSL certificate.
	object	No	The SSL certificate.
Id	string	No	The SSL certificate ID. Note This parameter is required only for HTTPS listeners.	449****-cn-hangzhou
BackendPorts	array<object>	No	The port range used by the backend server to receive requests.
	object	No	The port range used by the backend server to receive requests.
FromPort	integer	No	The first port in the range of ports used by the backend server to receive requests. Note This parameter is required only when the listener protocol is HTTP or HTTPS and the listener port is different from the port on which the backend server provides services. The first port must be the same as the last port.	80
ToPort	integer	No	The last port in the range of ports used by the backend server to receive requests. Note This parameter is required only when the listener protocol is HTTP or HTTPS and the listener port is different from the port on which the backend server provides services. The first port must be the same as the last port.	80
XForwardedForConfig	object	No	The `XForward` field configuration.
XForwardedForGaIdEnabled	boolean	No	Specifies whether to use the `GA-ID` header to retrieve the instance ID of the Alibaba Cloud Global Accelerator (GA). Valid values: true false (default) Note Only HTTP and HTTPS listeners support this parameter.	false
XForwardedForProtoEnabled	boolean	No	Specifies whether to use the `GA-X-Forward-Proto` header to retrieve the listener protocol of the Alibaba Cloud Global Accelerator (GA) instance. Valid values: true false (default) Note Only HTTP and HTTPS listeners support this parameter.	false
XForwardedForPortEnabled	boolean	No	Specifies whether to use the `GA-X-Forward-Port` header to retrieve the listener port of the Alibaba Cloud Global Accelerator (GA) instance. Valid values: true false (default) Note Only HTTP and HTTPS listeners support this parameter.	false
XRealIpEnabled	boolean	No	Specifies whether to use the `X-Real-IP` header to retrieve the originating IP address of the client. Valid values: true false (default) Note Only HTTP and HTTPS listeners support this parameter.	false
XForwardedForGaApEnabled	boolean	No	Specifies whether to use the `GA-AP` header to retrieve the acceleration area information. Valid values: true false (default) Note Only HTTP and HTTPS listeners support this parameter.	false
SecurityPolicyId	string	No	The security policy instance ID. Valid values: tls_cipher_policy_1_0 Supported TLS versions: TLSv1.0, TLSv1.1, and TLSv1.2. Supported encryption algorithm 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: TLSv1.1 and TLSv1.2. Supported encryption algorithm 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 versions: TLSv1.2. Supported encryption algorithm 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 versions: TLSv1.2. Supported encryption algorithm 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: TLSv1.2 and TLSv1.3. Supported encryption algorithm 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.	tls_cipher_policy_1_0
IdleTimeout	integer	No	The timeout period of idle connections. Unit: seconds. TCP: 10 to 900. Default value: 900. UDP: 10 to 20. Default value: 20. HTTP/HTTPS: 1 to 60. Default value: 15.	900
RequestTimeout	integer	No	The timeout period of HTTP/HTTPS connection requests. Unit: seconds. Valid values: 1 to 180. Default value: 60. Note This parameter takes effect only for listeners whose Protocol (network transmission protocol type) is HTTP or HTTPS. If the backend server does not return a response within the timeout period, Global Accelerator stops waiting and returns an HTTP 504 error code to the client.	60
HttpVersion	string	No	The maximum version of the HTTP protocol. Valid values: http3: HTTP/3. http2: HTTP/2. http1.1: HTTP/1.1. Note Only HTTPS listeners support this parameter.	http2

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	6FEA0CF3-D3B9-43E5-A304-D217037876A8

Examples

Success response

JSON format

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

Error codes

HTTP status code	Error code	Error message	Description
400	NotActive.Listener	The state of the listener is not active.	The listener is unstable.
400	PortRangeIllegal.Listener	The specified listener port range is invalid.	The specified listener port range is invalid.
400	PortConflict.Listener	The listener port configuration is in conflict.	The listener port configurations are in conflict.
400	QuotaExceeded.ListenerPort	The maximum number of listener ports is exceeded.	The maximum number of listener ports is exceeded.
400	NotExist.Accelerator	The accelerated instance does not exist.	The GA instance does not exist.
400	StateError.Accelerator	The state of the accelerated instance is invalid.	The status of the GA instance is invalid.
400	Exist.PortOverride	Port override exists.	The port mapping already exists.
400	RegionNotSupportHugePort.Listener	The current ipSet or listener region does not support hugePort.
400	PortRanges.MustOne	The portRanges must be one for HTTPS and HTTP type listener.	Only one port is supported for HTTPS and HTTP type listeners.
400	SecurityPolicyIdIllegal.Listener	The listener security policy ID %s is illegal.	The security policy ID of the listener is invalid.
400	SecurityPolicyId.NotNeed	No security policy ID is required for the listener.	No security policy ID is required for the listener.
500	UnknownError	An error occurred while processing your request. Please try again. If the error persists, please submit a ticket.	An error occurred while the request was being processed. Try again later.
403	Forbbiden.SubUser	You are not authorized to operate on the specified resource because your account was created by another user.	The current account is a RAM user and does not have permissions to manage the specified resources.
403	Forbidden	The user is not authorized to operate on the specified resource.	The current account does not have permissions to manage the specified resources.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.