Creates a listener for a Global Accelerator (GA) instance.

Description

A listener listens for connection requests and distributes the requests to endpoints based on forwarding rules that are defined by the scheduling algorithm. This API operation is used to create a listener for a GA instance.

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 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 ensure that it is unique among different requests. The token can contain only 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.

  • 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.
  • If this parameter is set to SOURCE_IP, client affinity is enabled. In this case, when a client accesses stateful applications, requests from the same client are 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
ProxyProtocol Boolean No false

Specifies whether to preserve client IP addresses. Valid values:

  • true: preserves client IP addresses. After this feature is enabled, backend servers can retrieve client IP addresses.
  • false (default): does not preserve client IP addresses.
Note This parameter will be deprecated from 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.
XForwardedForConfig Object No

The configuration of the XForward field.

XForwardedForGaIdEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForGaApEnabled Boolean No false

Specifies whether to use the GA-AP header to retrieve the information about the acceleration area. Valid values:

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XForwardedForPortEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
XRealIpEnabled Boolean No false

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

  • true: yes
  • false (default): no
Note Only HTTP and HTTPS listeners support this parameter.
SecurityPolicyId String No tls_cipher_policy_1_0

The ID of the security policy. Valid values:

  • tls_cipher_policy_1_0
    • Supported 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 Only HTTPS listeners support this parameter.
PortRanges.N.FromPort Integer Yes 20

The starting listener port that is used to receive and forward requests to endpoints.

Note You can configure only one listener port for an HTTP or HTTPS listener. In this case, the starting and ending listener ports are the same.
PortRanges.N.ToPort Integer Yes 20

The ending listener port that is 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.

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"}]
&XForwardedForConfig={"XForwardedForGaIdEnabled":false,"XForwardedForGaApEnabled":false,"XForwardedForProtoEnabled":false,"XForwardedForPortEnabled":false,"XRealIpEnabled":false}
&SecurityPolicyId=tls_cipher_policy_1_0
&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

HttpCode Error code Error message Description
400 ProtocalIllegal.Listener The specified listener protocol is invalid. The error message returned because the protocol of the specified 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 in an invalid state.
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 listener ports has reached the upper limit.
400 PortRangeIllegal.Listener The specified listener port range is invalid. The error message returned because the specified port range is invalid.
400 PortRangeIllegal.Count The hugePort listener only supports one port range. The error message returned because you can specify only one port range 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 specified listener port is already used.
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 listener port range is invalid. For each GA instance, you can create only one TCP and one UDP listener with a port range greater than 300.
400 PortRangeIllegal.UDP UDP ports 250, 4789, and 4790 are system reserved ports. The error message returned because you cannot specify port 250, port 4789, or port 4790 for UDP listeners. They are reserved by the system.
400 SystemPort.Listener Ports 65500-65535 are system reserved ports. The error message returned because ports 65500 to 65535 are reserved by the system.
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 SecurityPolicyId.NotNeed No security policy ID is required for the listener. The error message returned because you do not need to configure the security policy ID for the specified listener.
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.

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