Queries the information about 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 DescribeListener

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

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.

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 when the listener was created.

PortRanges Array of PortRanges

The information about the listening ports.

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

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

BackendPorts Array of BackendPort

The information about the backend ports.

FromPort String 80

The first port in the range of ports used by the backend server to receive requests.

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

ToPort String 80

The last port in the range of ports 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. The value Server 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
  • 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.
ListenerId String lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

ClientAffinity String SOURCE_IP

Indicates whether client affinity is enabled for the listener. Default value: NONE.

  • If NONE is returned, client affinity is disabled. When client affinity is disabled, requests from the same client are not always forwarded to the same endpoint.
  • If SOURCE_IP is returned, client affinity is enabled. In this case, requests from the same client to access stateful applications are always forwarded to the same endpoint regardless of the source ports or protocols.
Name String Listener

The name of the listener.

RelatedAcls Array of relatedAcls

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

AclId String 123

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

Status String off

Indicates whether the access control feature is enabled. Default value: off.

Valid values: on and off.

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. If you specify the ACL as a whitelist, errors may occur. Proceed with caution. After you configure a whitelist for a listener, only requests from the IP addresses that are added to the whitelist are forwarded 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 reserved. Default value: false. Valid values:

  • true: Client IP addresses are reserved. In this case, you can view the source IP addresses of clients over the backend service.
  • false: Client IP addresses are not reserved.
Note We recommend that you configure this parameter when you create an endpoint group. In the future, this parameter will be depreciated from API operations that relate to listeners. For more information about the ProxyProtocol parameter, see CreateEndpointGroup and UpdateEndpointGroup.

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>
</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
}

Error codes

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