Creates 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 CreateListener

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

RegionId String Yes cn-hangzhou

The ID of the region in which 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.

AcceleratorId String Yes ga-bp1odcab8tmno0hdq****

The ID of the GA instance.

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.

  • By default, this parameter is left empty. In this case, 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. After client affinity is enabled, requests from the same client to access stateful applications are always forwarded to the same endpoint regardless of the source ports or protocols.
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 apply to add your Alibaba Cloud account to the whitelist, submit a ticket.
ProxyProtocol Boolean 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: reserves no client IP addresses.
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 20

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 if an HTTPS listener is created.

Response parameters

Parameter Type Example Description
RequestId String 04F0F334-1335-436C-A1D7-6C044FE73368

The ID of the request.

ListenerId String lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateListener
&RegionId=cn-hangzhou
&ClientToken=123e4567-e89b-12d3-a456-426655440000    
&AcceleratorId=ga-bp1odcab8tmno0hdq****
&Name=Listener
&Description=Listener
&ClientAffinity=SOURCE_IP
&Protocol=tcp
&ProxyProtocol=false
&PortRanges=[{"FromPort":20,"ToPort":20}]
&Certificates=[{"Id":"449****-cn-hangzhou"}]
&<Common request parameters>

Sample success responses

XML format

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

<CreateListenerResponse>
    <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
    <ListenerId>lsr-bp1bpn0kn908w4nbw****</ListenerId>
</CreateListenerResponse>

JSON format

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

{
  "RequestId" : "04F0F334-1335-436C-A1D7-6C044FE73368",
  "ListenerId" : "lsr-bp1bpn0kn908w4nbw****"
}

Error codes

HTTP status code Error code Error message Description
400 ProtocalIllegal.Listener The specified listener protocol is invalid. The error message returned because the protocol for the configured listener is invalid.
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 QuotaExceeded.Listener The maximum number of listeners is exceeded. The error message returned because the number of listeners has reached the upper limit.
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 PortRangeIllegal.Listener The specified listener port range is invalid. The error message returned because the specified listening port range is invalid.
400 PortRangeIllegal.Count The hugePort listener only supports one port range. The error message returned because only one listening port range can be configured for a listener that supports more than 300 ports.
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 PortRangeIllegal.ExceedGaAbility The listener port range is invalid. For each accelerator instance, you can only create a listener with port range over 300 for each protocol (TCP and UDP). The error message returned because the listening port range is invalid. For each GA instance, you can create only one listener of which the listening port range covers more than 300 ports for each of the TCP and UDP protocols.
400 PortRangeIllegal.UDP UDP ports 250, 4789, and 4790 are system reserved ports. The error message returned because ports 250, 4789, and 4790 are system-reserved UDP ports.
400 SystemPort.Listener Ports 65500-65535 are system reserved ports. The error message returned because ports 65500 to 65535 are system-reserved 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.