Queries information about a specified listener of a Global Accelerator (GA) instance.

Description

This API operation is used to query information about a specified listener of a GA instance. The information includes the status of the listener, the timestamp that indicates when the listener was created, and the listener ports.

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 DescribeListener

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

RegionId String Yes cn-hangzhou

The ID of the region where the GA instance is deployed. Set the value to cn-hangzhou.

ListenerId String Yes lsr-bp1bpn0kn908w4nbw****

The ID of the listener that you want to query.

Response parameters

Parameter Type Example Description
Description String Listener

The description of the listener.

RequestId String 6FEA0CF3-D3B9-43E5-A304-D217037876A8

The ID of the request.

State String active

The status of the listener. Valid values:

  • active: The listener is running as expected.
  • creating: The listener is being created.
  • configuring: The listener is being configured.
CreateTime String 1577786252000

The timestamp that indicates when the listener was created.

PortRanges Array of PortRanges

The information about the listener ports.

FromPort Integer 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.
ToPort Integer 20

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

BackendPorts Array of BackendPort

The information about the backend ports.

FromPort String 80

The starting port that is used by the backend server to receive requests.

This parameter is returned only when you configure an HTTPS listener and the listener port is the same port used by the backend server to provide services.

ToPort String 80

The ending port that is used by the backend server to receive requests.

Certificates Array of Certificate

The SSL certificates.

Type String Server

The type of the certificate.

Only Server can be returned, which indicates a server certificate.

Id String 449****-cn-hangzhou

The ID of the SSL certificate.

Protocol String TCP

The network transmission protocol that is used by the listener. Valid values:

  • tcp: TCP
  • udp: UDP
  • http: HTTP
  • https: HTTPS
ListenerId String lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

ClientAffinity String SOURCE_IP

Indicates whether client affinity is enabled for the listener.

  • If NONE is returned, client affinity is disabled. After client affinity is disabled, requests from a specific client IP address may be forwarded to different endpoints.
  • If SOURCE_IP is returned, 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.
Name String Listener

The name of the listener.

RelatedAcls Array of relatedAcls

The information about the access control list (ACL) that is associated with the listener.

AclId String 123

The ID of the ACL that is associated with the listener.

Status String off

Indicates whether the access control feature is enabled. Valid values:

  • on: enabled
  • off: disabled
AclType String white

The type of the ACL. Valid values:

  • white: a whitelist. Only requests from the IP addresses or CIDR blocks in the ACL are forwarded. A whitelist is suitable for scenarios in which you want to allow only specific IP addresses to access an application. Your business may be affected if the whitelist is not set properly. After you configure a whitelist for a listener, only requests from the IP addresses that are added to the whitelist are distributed by the listener. If the whitelist is enabled but no IP addresses are added to the ACL, the listener does not forward requests.
  • black: a blacklist. All requests from the IP addresses or CIDR blocks in the ACL are blocked. A blacklist is suitable for scenarios in which you want to block access from specific IP addresses or CIDR blocks to an application. If the blacklist is enabled but no IP addresses or CIDR blocks are added to the ACL, the listener forwards all requests.

If the value of Status is on, this parameter is returned.

AcceleratorId String ga-bp1odcab8tmno0hdq****

The ID of the GA instance.

ProxyProtocol Boolean false

Indicates whether client IP addresses are preserved. Valid values:

  • true: client IP addresses are preserved. After this feature is enabled, backend servers can retrieve client IP addresses.
  • false: client IP addresses are not preserved.
XForwardedForConfig Object

The configuration of the XForward field.

XForwardedForGaIdEnabled Boolean false

Indicates whether the GA-ID header is used to retrieve the ID of the GA instance. Valid values:

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

Indicates whether the GA-AP header is used to retrieve the information about the acceleration area. Valid values:

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

Indicates whether the GA-X-Forward-Proto header is used to retrieve the listener protocol of the GA instance. Valid values:

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

Indicates whether the GA-X-Forward-Port header is used to retrieve the listener ports of the GA instance. Valid values:

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

Indicates whether the X-Real-IP header is used to retrieve client IP addresses. Valid values:

  • true: yes
  • false: no
Note Only HTTP and HTTPS listeners support this parameter.
SecurityPolicyId String 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.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeListener
&RegionId=cn-hangzhou
&ListenerId=lsr-bp1bpn0kn908w4nbw****
&Common request parameters

Sample success responses

XML format 

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

<DescribeListenerResponse>
    <Description>Listener</Description>
    <RequestId>6FEA0CF3-D3B9-43E5-A304-D217037876A8	</RequestId>
    <State>active</State>
    <CreateTime>1577786252000</CreateTime>
    <PortRanges>
        <FromPort>20</FromPort>
        <ToPort>20</ToPort>
    </PortRanges>
    <BackendPorts>
        <FromPort>80</FromPort>
        <ToPort>80</ToPort>
    </BackendPorts>
    <Certificates>
        <Type>Server</Type>
        <Id>449****-cn-hangzhou</Id>
    </Certificates>
    <Protocol>TCP</Protocol>
    <ListenerId>lsr-bp1bpn0kn908w4nbw****</ListenerId>
    <ClientAffinity>SOURCE_IP</ClientAffinity>
    <Name>Listener</Name>
    <RelatedAcls>
        <AclId>123</AclId>
        <Status>off</Status>
    </RelatedAcls>
    <AclType>white</AclType>
    <AcceleratorId>ga-bp1odcab8tmno0hdq****</AcceleratorId>
    <ProxyProtocol>false</ProxyProtocol>
    <XForwardedForConfig>
        <XForwardedForGaIdEnabled>false</XForwardedForGaIdEnabled>
        <XForwardedForGaApEnabled>false</XForwardedForGaApEnabled>
        <XForwardedForProtoEnabled>false</XForwardedForProtoEnabled>
        <XForwardedForPortEnabled>false</XForwardedForPortEnabled>
        <XRealIpEnabled>false</XRealIpEnabled>
    </XForwardedForConfig>
    <SecurityPolicyId>tls_cipher_policy_1_0</SecurityPolicyId>
</DescribeListenerResponse>

JSON format 

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

{
  "Description" : "Listener",
  "RequestId" : "6FEA0CF3-D3B9-43E5-A304-D217037876A8\t",
  "State" : "active",
  "CreateTime" : "1577786252000",
  "PortRanges" : [ {
    "FromPort" : 20,
    "ToPort" : 20
  } ],
  "BackendPorts" : [ {
    "FromPort" : "80",
    "ToPort" : "80"
  } ],
  "Certificates" : [ {
    "Type" : "Server",
    "Id" : "449****-cn-hangzhou"
  } ],
  "Protocol" : "TCP",
  "ListenerId" : "lsr-bp1bpn0kn908w4nbw****",
  "ClientAffinity" : "SOURCE_IP",
  "Name" : "Listener",
  "RelatedAcls" : [ {
    "AclId" : "123",
    "Status" : "off"
  } ],
  "AclType" : "white",
  "AcceleratorId" : "ga-bp1odcab8tmno0hdq****",
  "ProxyProtocol" : false,
  "XForwardedForConfig" : {
    "XForwardedForGaIdEnabled" : false,
    "XForwardedForGaApEnabled" : false,
    "XForwardedForProtoEnabled" : false,
    "XForwardedForPortEnabled" : false,
    "XRealIpEnabled" : false
  },
  "SecurityPolicyId" : "tls_cipher_policy_1_0"
}

Error codes

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