• Elastic Load Balancing

elb
  1. Help Center
  2. Elastic Load Balancing
  3. API Reference
  4. Enhanced Load Balancer APIs
  5. Listener
  6. Querying Listeners

Querying Listeners

Function

This API is used to query all listeners and display them in a list. Filter query and pagination query are supported.

You can query listeners by listener ID, listener protocol, listener port number, and backend server private IP address.

URI

GET /v2.0/lbaas/listeners

Constraints

Parameters marker, limit, and page_reverse are used for pagination query. Parameters marker and page_reverse take effect only when they are used together with parameter limit.

Request

Table 1 Parameter description

Parameter

Type

Mandatory

Description

marker

String

No

Specifies the ID of the listener from which pagination query starts, that is, the ID of the last listener on the previous page.

This parameter must be used together with limit.

limit

Int

No

Specifies the number of listeners on each page.

The value ranges from 0 to intmax.

page_reverse

Bool

No

Specifies the page direction. The value can be true or false, and the default value is false. The last page in the list requested with page_reverse set to false will not contain the "next" link, and the last page in the list requested with page_reverse set to true will not contain the "previous" link.

This parameter must be used together with limit.

id

Uuid

No

Specifies the listener ID.

tenant_id

String (255)

No

Specifies the ID of the project where the listener is used.

name

String (255)

No

Specifies the listener name.

description

String (255)

No

Provides supplementary information about the listener.

default_pool_id

Uuid

No

Specifies the ID of the associated backend server group.

If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing.

default_tls_container_ref

String (128)

No

Specifies the ID of the server certificate used by the listener.

client_ca_tls_container_ref

String (128)

No

Specifies the ID of the CA certificate used by the listener.

protocol

String

No

Specifies the listener protocol.

The value can be TCP, HTTP, UDP, or TERMINATED_HTTPS.

protocol_port

Int

No

Specifies the listening port.

The port number ranges from 1 to 65535.

Response

Table 2 Parameter description

Parameter

Type

Description

listeners

List

Lists the listeners. For details, see Table 3.

Table 3 listeners field description

Parameter

Type

Description

id

Uuid

Specifies the listener ID.

tenant_id

String (255)

Specifies the ID of the project where the listener is used.

name

String (255)

Specifies the listener name.

description

String (255)

Provides supplementary information about the listener.

protocol

String

Specifies the listener protocol.

The value can be TCP, HTTP, UDP, or TERMINATED_HTTPS.

protocol_port

Int

Specifies the listening port.

The port number ranges from 1 to 65535.

loadbalancers

Uuid

Lists the IDs of load balancers associated with the listener.

connection_limit

Int

Specifies the maximum number of connections.

The value ranges from -1 to 2,147,483,647.

NOTE:

This parameter is reserved and has been not used. The default value is -1, indicating that there is no restriction on maximum connections.

admin_state_up

Bool

Specifies the administrative status of the listener.

NOTE:

This parameter is reserved and has been not used. The value can only be true.

http2_enable

Bool

Specifies whether to use HTTP/2.

The value can be true or false. true: HTTP/2 will be used. false: HTTP/2 will not be used.

NOTE:

This parameter is valid only when the listener protocol is set to TERMINATED_HTTPS.

default_pool_id

Uuid

Specifies the ID of the associated backend server group.

NOTE:

If a request does not match the forwarding policy, the request is forwarded to the default backend server group for processing. If the value is null, the listener has no default backend server group.

default_tls_container_ref

String (128)

Specifies the ID of the server certificate used by the listener.

This parameter is mandatory when protocol is set to TERMINATED_HTTPS.

client_ca_tls_container_ref

String (128)

Specifies the ID of the CA certificate used by the listener.

sni_container_refs

List

Lists the IDs of SNI certificates (server certificates with a domain name) used by the listener.

tags

List

Tags the listener.

created_at

String (19)

Specifies the time when a listener was created. The time is in YYYY-MM-DDTHH:MM:SS format.

updated_at

String (19)

Specifies the time when the listener was updated. The time is in YYYY-MM-DDTHH:MM:SS format.

listeners_links

List

Provides links to the previous or next page during pagination query, respectively. Specifies information about the previous or next page.

Table 4 listeners_links field description

Parameter

Type

Description

href

String

Provides links to the previous or next page during pagination query, respectively.

rel

String (255)

Specifies the prompt of the previous or next page.

The value can be next or previous. The value next indicates the href containing the URL of the next page, and previous indicates the href containing the URL of the previous page.

Example

  • Example request 1: Querying all listeners
    GET https://{Endpoint}/v2.0/lbaas/listeners
  • Example response 1
    {
        "listeners": [
            {
                "client_ca_tls_container_ref": null,
                "protocol": "TCP",
                "description": "",
                "default_tls_container_ref": null,
                "admin_state_up": true,
                "http2_enable": false,
                "loadbalancers": [
                    {
                        "id": "bc7ba445-035a-4464-a1a3-a62cf4a14116"
                    }
                ],
                "tenant_id": "601240b9c5c94059b63d484c92cfe308",
                
                "sni_container_refs": [],
                "connection_limit": -1,
                "protocol_port": 80,
                "default_pool_id": "ed75f16e-fcc6-403e-a3fb-4eae82005eab",
                "id": "75045172-70e9-480d-9443-b8b6459948f7",
                "tags": []
                "name": "listener-cb2n",
                "created_at": "2018-07-25T01:54:13", 
                "updated_at": "2018-07-25T01:54:14"
               
            },
            {
                "client_ca_tls_container_ref": null,
                "protocol": "TCP",
                "description": "",
                "default_tls_container_ref": null,
                "admin_state_up": true,
                "http2_enable": false,
                "loadbalancers": [
                    {
                        "id": "165b6a38-5278-4569-b747-b2ee65ea84a4"
                    }
                ],
                "tenant_id": "601240b9c5c94059b63d484c92cfe308",
                
                "sni_container_refs": [],
                "connection_limit": -1,
                "protocol_port": 8080,
                "default_pool_id": null,
                "id": "dada0003-7b0e-4de8-a4e1-1e937be2ba14",
                "tags": [],
                "name": "lsnr_name_mod",
                "created_at": "2018-07-25T01:54:13", 
                "updated_at": "2018-07-25T01:54:14"
                
            }
        ],
        "listeners_links": [
            {
                "href": "https://network.Region.dc1.domainname.com/v2.0/lbaas/listeners?protocol=TCP&limit=10&marker=75045172-70e9-480d-9443-b8b6459948f7&page_reverse=True",
                "rel": "previous"
            }
        ]
    }
  • Example request 2: Filtering a listener whose protocol type is UDP using the IP address of an associated backend server (192.168.0.191)
    GET https://{Endpoint}/v2.0/lbaas/listeners?member_address=192.168.0.191&protocol=UDP
  • Example response 2
    {
        "listeners": [
            {
                "insert_headers": null,
                "protocol_port": 64809,
                "protocol": "UDP",
                "description": "",
                "default_tls_container_ref": null,
                "sni_container_refs": [],
                "loadbalancers": [
                    {
                        "id": "c1127125-64a9-4394-a08a-ef3be8f7ef9c"
                    }
                ],
                "tenant_id": "601240b9c5c94059b63d484c92cfe308",
                
                "created_at": "2018-11-29T13:56:21",
                "client_ca_tls_container_ref": null,
                "connection_limit": -1,
                "updated_at": "2018-11-29T13:56:22",
                "http2_enable": false,
                "admin_state_up": true,
                "default_pool_id": "2f6895be-019b-4c82-9b53-c4a2ac009e20",
                "id": "5c63d176-444f-4c75-9cfe-bcb8a05a845c",
                "tags": [],
                "name": "listener-tvp8"
            }
        ]
    }

Response Codes

For details, see HTTP Status Codes for Enhanced Load Balancers.