Modifies 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 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 Global Accelerator (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 only contain 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. If client affinity is disabled, requests from the same client are not always forwarded to the same endpoint.
  • 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
  • udp
  • http
  • https
Note You can create HTTP and HTTPS listeners only if your Alibaba Cloud account is added to the whitelist. To use this feature, submit a ticket.
ListenerId String Yes lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

ProxyProtocol String No false

Specifies whether to reserve client IP addresses. 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: reserves no client IP addresses. This is the default value.
PortRanges.N.FromPort Integer Yes 20

The first port in the range of listening ports used to receive and forward requests to endpoints.

Note You can configure only one listening port for an HTTP or HTTPS listener. In this case, the first port also serves as the last port.
PortRanges.N.ToPort Integer Yes 21

The last port in the range of listening ports 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 first 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 listener and the listening port is the same port over which the backend server provides services. In this case, the first port that is used to receive requests for the backend server must serve as the last port.
BackendPorts.N.ToPort Integer No 80

The last port in the range of ports 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}]
&<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

HTTP status code 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 listening port range is invalid.
400 PortConflict.Listener The listener port configuration is in conflict. The error message returned because the range of listening ports for the configured listener contains ports that are reserved for another listener that uses the same protocol.
400 QuotaExceeded.ListenerPort The maximum number of listener ports is exceeded. The error message returned because the number of listening 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 invalid.
400 RegionNotSupportHugePort.Listener The current ipSet or listener region does not support hugePort. The region of the acceleration area or the endpoint group does not support a large number of ports.
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.

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