Modifies the configurations of a listener for a Global Accelerator (GA) instance.
Operation description
This operation can be called to modify the configurations such as the 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 and runs the task in the background. You can call the DescribeListener operation to query the status 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
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.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
ga:UpdateListener | update |
|
| none |
Request parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
RegionId | string | No | The region ID of the 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 request ID as the client token. The request ID may be different for each 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 (-). The name must start with a letter. | Listener |
Description | string | No | The description of the listener. The description can be up to 200 characters in length and cannot start with | Listener |
ClientAffinity | string | No | Indicates whether client affinity is enabled for the listener. Valid values:
| SOURCE_IP |
Protocol | string | No | The network transmission protocol that is used by the listener. Valid values:
| tcp |
ListenerId | string | Yes | The ID of the listener. | lsr-bp1bpn0kn908w4nbw**** |
ProxyProtocol | string | No | Specifies whether to reserve client IP addresses. Default value: false. Valid values:
Note
This parameter will be deprecated 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 .
| false |
PortRanges | array<object> | No | The listener ports that are used to receive requests and forward the requests to endpoints. Valid values: 1 to 65499. The maximum number of ports that can be configured varies based on the routing type and protocol of the listener. For more information, see Listener overview. | |
object | No | The listener ports that are used to receive requests and forward the requests to endpoints. Valid values: 1 to 65499. The maximum number of ports that can be configured varies based on the routing type and protocol of the listener. For more information, see Listener overview. | ||
FromPort | integer | Yes | The first 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 varies based on 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 first port is the same as the last port.
| 20 |
ToPort | integer | Yes | The last 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 varies based on 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 first port is the same as the last port.
| 21 |
Certificates | array<object> | No | The SSL certificate. | |
object | No | The SSL certificate. | ||
Id | string | No | The ID of the SSL certificate. Note
This parameter is required only when you configure an HTTPS listener.
| 449****-cn-hangzhou |
BackendPorts | array<object> | No | The range of ports that are used by backend servers to receive requests. | |
object | No | The range of ports that are used by backend servers to receive requests. | ||
FromPort | integer | No | The first port in the range of ports that are used by backend servers 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 service port of the backend servers. In this case, the first port that is used by the backend servers to receive requests must be the same as the last port.
| 80 |
ToPort | integer | No | The last port in the range of ports that are used by backend servers 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 service port of the backend servers. In this case, the first port that is used by the backend servers to receive requests must be the same as the last port.
| 80 |
XForwardedForConfig | object | No | The | |
XForwardedForGaIdEnabled | boolean | No | Specifies whether to use the
Note
This parameter is available only when you create an HTTPS or HTTP listener.
| false |
XForwardedForProtoEnabled | boolean | No | Specifies whether to use the
Note
This parameter is available only when you create an HTTPS or HTTP listener.
| false |
XForwardedForPortEnabled | boolean | No | Specifies whether to use the
Note
This parameter is available only when you create an HTTPS or HTTP listener.
| false |
XRealIpEnabled | boolean | No | Specifies whether to use the
Note
This parameter is available only when you create an HTTPS or HTTP listener.
| false |
XForwardedForGaApEnabled | boolean | No | Specifies whether to use the
Note
This parameter is available only when you create an HTTPS or HTTP listener.
| false |
SecurityPolicyId | string | No | The ID of the security policy. Valid values:
Note
This parameter is available only when you create an HTTPS listener.
| tls_cipher_policy_1_0 |
IdleTimeout | integer | No | The timeout period for idle connections. Unit: seconds.
| 900 |
RequestTimeout | integer | No | The timeout period for HTTP or HTTPS requests. Valid values: 1 to 180. Default value: 60. Unit: seconds. Note
This parameter takes effect only for HTTP or HTTPS listeners. If the backend server does not respond within the timeout period, GA returns an HTTP 504 error code to the client.
| 60 |
HttpVersion | string | No | The maximum version of the HTTP protocol. Valid values:
Note
Only HTTPS listeners support this parameter.
| http2 |
Response parameters
Examples
Sample success responses
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. |
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. |
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. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-03-27 | The Error code has changed. The request parameters of the API has changed | View Change Details |
2023-11-06 | The Error code has changed. The request parameters of the API has changed | View Change Details |