Querying Listeners
Function
This API is used to query listeners.
Constraints
This API has the following 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.
Calling Method
For details, see Calling APIs.
URI
GET /v3/{project_id}/elb/listeners
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Specifies the project ID. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
limit |
No |
Integer |
Specifies the number of records on each page. Minimum: 0 Maximum: 2000 Default: 2000 |
marker |
No |
String |
Specifies the ID of the last record on the previous page. Note:
|
page_reverse |
No |
Boolean |
Specifies whether to use reverse query. Values:
Note:
|
protocol_port |
No |
Array |
Specifies the port used by the listener. Multiple ports can be queried in the format of protocol_port=xxx&protocol_port=xxx. |
protocol |
No |
Array |
Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, HTTPS, TERMINATED_HTTPS, or QUIC. Note: TERMINATED_HTTPS is only available for the listeners of shared load balancers. Multiple protocols can be queried in the format of protocol=xxx&protocol=xxx. |
description |
No |
Array |
Provides supplementary information about the listener. Multiple descriptions can be queried in the format of description=xxx&description=xxx. |
default_tls_container_ref |
No |
Array |
Specifies the ID of the server certificate used by the listener. Multiple IDs can be queried in the format of default_tls_container_ref=xxx&default_tls_container_ref=xxx. |
client_ca_tls_container_ref |
No |
Array |
Specifies the ID of the CA certificate used by the listener. Multiple IDs can be queried in the format of client_ca_tls_container_ref=xxx&client_ca_tls_container_ref=xxx. |
admin_state_up |
No |
Boolean |
Specifies the administrative status of the listener. The value can only be true. This parameter is unsupported. Please do not use it. |
connection_limit |
No |
Array |
Specifies the maximum number of connections that the load balancer can establish with backend servers. The value -1 indicates that the number of connections is not limited. Multiple values can be queried in the format of connection_limit=xxx&connection_limit=xxx. This parameter is unsupported. Please do not use it. |
default_pool_id |
No |
Array |
Specifies the ID of the default backend server group. If there is no matched forwarding policy, requests will be routed to the default backend server. Multiple IDs can be queried in the format of default_pool_id=xxx&default_pool_id=xxx. |
id |
No |
Array |
Specifies the listener ID. Multiple IDs can be queried in the format of id=xxx&id=xxx. |
name |
No |
Array |
Specifies the name of the listener added to the load balancer. Multiple names can be queried in the format of name=xxx&name=xxx. |
http2_enable |
No |
Boolean |
Specifies whether to use HTTP/2 if you want the clients to use HTTP/2 to communicate with the listener. However, connections between the load balancer and backend servers still use HTTP/1.x by default. Note:
|
loadbalancer_id |
No |
Array |
Specifies the ID of the load balancer that the listener is added to. Multiple IDs can be queried in the format of loadbalancer_id=xxx&loadbalancer_id=xxx. |
tls_ciphers_policy |
No |
Array |
Specifies the security policy used by the listener. Multiple security policies can be queried in the format of tls_ciphers_policy=xxx&tls_ciphers_policy=xxx. |
member_address |
No |
Array |
Specifies the private IP address bound to the backend server. This parameter is used only as a query condition and is not included in the response. Multiple IP addresses can be queried in the format of member_address=xxx&member_address=xxx. |
member_device_id |
No |
Array |
Specifies the ID of the cloud server that serves as a backend server. This parameter is used only as a query condition and is not included in the response. Multiple IDs can be queried in the format of member_device_id=xxx&member_device_id=xxx. |
enterprise_project_id |
No |
Array |
Specifies the enterprise project ID.
Multiple IDs can be queried in the format of enterprise_project_id=xxx&enterprise_project_id=xxx. |
enable_member_retry |
No |
Boolean |
Specifies whether to enable health check retries for backend servers. The value can be true (enable health check retries) or false (disable health check retries). |
member_timeout |
No |
Array |
Specifies the timeout duration for waiting for a response from a backend server, in seconds. If the backend server fails to respond after the timeout duration elapses, the load balancer will stop waiting and return HTTP 504 Gateway Timeout to the client. The value ranges from 1 to 300. Multiple durations can be queried in the format of member_timeout=xxx&member_timeout=xxx. |
client_timeout |
No |
Array |
Specifies the timeout duration for waiting for a response from a client, in seconds. There are two situations:
The value ranges from 1 to 300. Multiple durations can be queried in the format of client_timeout=xxx&client_timeout=xxx. |
keepalive_timeout |
No |
Array |
Specifies the idle timeout duration, in seconds. If there are no requests reaching the load balancer after the idle timeout duration elapses, the load balancer will disconnect the connection with the client and establish a new connection when there is a new request.
Multiple durations can be queried in the format of keepalive_timeout=xxx&keepalive_timeout=xxx. |
transparent_client_ip_enable |
No |
Boolean |
Specifies whether to pass source IP addresses of the clients to backend servers. This parameter is only available for TCP or UDP listeners of shared load balancers.
|
proxy_protocol_enable |
No |
Boolean |
Specifies whether to enable the ProxyProtocol option to pass the source IP addresses of the clients to backend servers. This parameter is available only for TLS listeners and does not take effect for other types of listeners. |
enhance_l7policy_enable |
No |
Boolean |
Specifies whether to enable advanced forwarding. If you enable this function, you can configure more flexible forwarding policies and rules.
|
member_instance_id |
No |
Array |
Specifies the backend server ID. This parameter is used only as a query condition and is not included in the response. Multiple IDs can be queried in the format of member_instance_id=xxx&member_instance_id=xxx. |
Request Parameters
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
X-Auth-Token |
Yes |
String |
Specifies the token used for IAM authentication. |
Response Parameters
Status code: 200
Parameter |
Type |
Description |
---|---|---|
request_id |
String |
Specifies the request ID. The value is automatically generated. |
page_info |
PageInfo object |
Shows pagination information about listeners. |
listeners |
Array of Listener objects |
Lists the listeners. |
Parameter |
Type |
Description |
---|---|---|
previous_marker |
String |
Specifies the ID of the first record in the pagination query result. |
next_marker |
String |
Specifies the ID of the last record in the pagination query result. |
current_count |
Integer |
Specifies the number of records. |
Parameter |
Type |
Description |
---|---|---|
admin_state_up |
Boolean |
Specifies the administrative status of the listener. The value can only be true. This parameter is unsupported. Please do not use it. |
client_ca_tls_container_ref |
String |
Specifies the ID of the CA certificate used by the listener. This parameter is available only when type is set to client. |
connection_limit |
Integer |
Specifies the maximum number of connections that the load balancer can establish with backend servers. The value -1 indicates that the number of connections is not limited. This parameter is unsupported. Please do not use it. |
created_at |
String |
Specifies the time when the listener was created, in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z. |
default_pool_id |
String |
Specifies the ID of the default backend server group. If there is no matched forwarding policy, requests are forwarded to the default backend server. |
default_tls_container_ref |
String |
Specifies the ID of the server certificate used by the listener. |
description |
String |
Provides supplementary information about the listener. |
http2_enable |
Boolean |
Specifies whether to use HTTP/2 if you want the clients to use HTTP/2 to communicate with the listener. However, connections between the load balancer and backend servers still use HTTP/1.x by default. Note:
|
id |
String |
Specifies the listener ID. |
insert_headers |
ListenerInsertHeaders object |
Specifies the HTTP header fields that can transmit required information to backend servers. For example, the X-Forwarded-ELB-IP header field can transmit the EIP of the load balancer to backend servers. |
loadbalancers |
Array of LoadBalancerRef objects |
Specifies the ID of the load balancer that the listener is added to. A listener can be added to only one load balancer. |
name |
String |
Specifies the listener name. Note: If you leave the listener name empty, you cannot locate it on the listener list and view its details. |
project_id |
String |
Specifies the ID of the project where the listener is used. |
protocol |
String |
Specifies the protocol used by the listener. The value can be TCP, HTTP, UDP, HTTPS, TERMINATED_HTTPS, QUIC, or TLS. Note:
|
protocol_port |
Integer |
Specifies the port used by the listener. The QUIC listener port cannot be 4789 or the same as the UDP listener port. If this parameter is set to 0, port_ranges is required. Minimum: 0 Maximum: 65535 |
sni_container_refs |
Array of strings |
Specifies the IDs of SNI certificates (server certificates with domain names) used by the listener. Note:
|
sni_match_algo |
String |
Specifies how wildcard domain name matches with the SNI certificates used by the listener. longest_suffix indicates longest suffix match. wildcard indicates wildcard match. The default value is wildcard. |
tags |
Array of Tag objects |
Lists the tags. |
updated_at |
String |
Specifies the time when the listener was updated, in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z. |
tls_ciphers_policy |
String |
Specifies the security policy used by the listener. |
security_policy_id |
String |
Specifies the ID of the custom security policy. |
enable_member_retry |
Boolean |
Specifies whether to enable health check retries for backend servers. The value can be true (enable health check retries) or false (disable health check retries). The default value is true. Note:
|
keepalive_timeout |
Integer |
Specifies the idle timeout duration, in seconds. If there are no requests reaching the load balancer after the idle timeout duration elapses, the load balancer will disconnect the connection with the client and establish a new connection when there is a new request.
|
client_timeout |
Integer |
Specifies the timeout duration for waiting for a response from a client, in seconds. There are two situations:
The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners. |
member_timeout |
Integer |
Specifies the timeout duration for waiting for a response from a backend server, in seconds. If the backend server fails to respond after the timeout duration elapses, the load balancer will stop waiting and return HTTP 504 Gateway Timeout to the client. The value ranges from 1 to 300, and the default value is 60. This parameter is available only for HTTP and HTTPS listeners. |
ipgroup |
ListenerIpGroup object |
Specifies the IP address group associated with the listener. |
transparent_client_ip_enable |
Boolean |
Specifies whether to pass source IP addresses of the clients to backend servers. |
proxy_protocol_enable |
Boolean |
Specifies whether to enable the ProxyProtocol option to pass the source IP addresses of the clients to backend servers. This parameter is available only for TLS listeners and does not take effect for other types of listeners. |
enhance_l7policy_enable |
Boolean |
Specifies whether to enable advanced forwarding. If advanced forwarding is enabled, more flexible forwarding policies and rules are supported. The value can be true (enable advanced forwarding) or false (disable advanced forwarding), and the default value is false. The following scenarios are supported:
Default: false |
quic_config |
ListenerQuicConfig object |
Specifies the QUIC configuration for the current listener. This parameter is valid only when protocol is set to HTTPS. For TCP, UDP, HTTP, QUIC listeners, if this parameter is not left blank, an error will be reported.
NOTE:
The client sends a normal HTTP request that contains information indicating that the QUIC protocol is supported. If QUIC upgrade is enabled for the listeners, QUIC port and version information will be added to the response header. When the client sends both HTTPS and QUIC requests to the server, if the QUIC request is successfully sent, QUIC protocol will be used for subsequent communications. |
Parameter |
Type |
Description |
---|---|---|
X-Forwarded-ELB-IP |
Boolean |
Specifies whether to transparently transmit the load balancer EIP to backend servers. If X-Forwarded-ELB-IP is set to true, the load balancer EIP will be stored in the HTTP header and passed to backend servers. |
X-Forwarded-Port |
Boolean |
Specifies whether to transparently transmit the listening port of the load balancer to backend servers. If X-Forwarded-Port is set to true, the listening port of the load balancer will be stored in the HTTP header and passed to backend servers. |
X-Forwarded-For-Port |
Boolean |
Specifies whether to transparently transmit the source port of the client to backend servers. If X-Forwarded-For-Port is set to true, the source port of the client will be stored in the HTTP header and passed to backend servers. |
X-Forwarded-Host |
Boolean |
Specifies whether to rewrite the X-Forwarded-Host header. If X-Forwarded-Host is set to true, X-Forwarded-Host in the request header from the clients can be set to Host in the request header sent from the load balancer to backend servers. |
X-Forwarded-Proto |
Boolean |
If X-Forwarded-Proto is set to true, the listener protocol of the load balancer can be transferred to backend servers through the HTTP header of the packet. |
X-Real-IP |
Boolean |
If X-Real-IP is set to true, the source IP address of the client can be transferred to backend servers through the HTTP header of the packet. |
X-Forwarded-ELB-ID |
Boolean |
If X-Forwarded-ELB-ID is set to true, the load balancer ID can be transferred to backend servers through the HTTP header of the packet. |
X-Forwarded-TLS-Certificate-ID |
Boolean |
If X-Forwarded-TLS-Certificate-ID is set to true, the certificate ID of the load balancer can be transferred to backend servers through the HTTP header of the packet. |
X-Forwarded-TLS-Protocol |
Boolean |
If X-Forwarded-TLS-Protocol is set to true, the algorithm protocol of the load balancer can be transferred to backend servers through the HTTP header of the packet. |
X-Forwarded-TLS-Cipher |
Boolean |
If X-Forwarded-TLS-Cipher is set to true, the algorithm suite of the load balancer can be transferred to backend servers through the HTTP header of the packet. |
Parameter |
Type |
Description |
---|---|---|
key |
String |
Specifies the tag key. Minimum: 1 Maximum: 36 |
value |
String |
Specifies the tag value. Minimum: 0 Maximum: 43 |
Parameter |
Type |
Description |
---|---|---|
ipgroup_id |
String |
Specifies the ID of the IP address group associated with the listener. This parameter is mandatory when you create the IP address group and is optional when you update the IP address group. The specified IP address group must exist, and the value cannot be null. |
enable_ipgroup |
Boolean |
Specifies whether to enable access control.
A listener with access control enabled can be directly deleted. |
type |
String |
Specifies how access to the listener is controlled.
|
Parameter |
Type |
Description |
---|---|---|
quic_listener_id |
String |
Specifies the ID of the QUIC listener. This parameter is mandatory for creation and is optional for update. The specified quic_listener_id must exist. The listener protocol must be QUIC and cannot be set to null, otherwise, it will conflict with enable_quic_upgrade. |
enable_quic_upgrade |
Boolean |
Specifies whether to enable QUIC upgrade. True: QUIC upgrade is enabled. False: QUIC upgrade is disabled. HTTPS listeners can be upgraded to QUIC listeners. |
Example Requests
Queries the listeners on each page
GET https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners?limit=2&marker=0r31747a-b139-492f-2749-2df0b1c87193
Example Responses
Status code: 200
Successful request.
{ "listeners" : [ { "id" : "0b11747a-b139-492f-9692-2df0b1c87193", "name" : "My listener", "protocol_port" : 80, "protocol" : "TCP", "ipgroup" : null, "description" : "My listener update.", "default_tls_container_ref" : null, "admin_state_up" : true, "loadbalancers" : [ { "id" : "098b2f68-af1c-41a9-8efd-69958722af62" } ], "member_timeout" : null, "client_timeout" : null, "keepalive_timeout" : 300, "client_ca_tls_container_ref" : null, "project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "sni_container_refs" : [ ], "connection_limit" : -1, "default_pool_id" : null, "tls_ciphers_policy" : "tls-1-0", "tags" : [ ], "created_at" : "2019-04-02T00:12:32Z", "updated_at" : "2019-04-02T17:43:46Z", "http2_enable" : true, "insert_headers" : { "X-Forwarded-ELB-IP" : true }, "transparent_client_ip_enable" : false, "quic_config" : null }, { "id" : "0b455839-3ea7-4bac-ad26-35bf22f96ea4", "name" : "listener-test", "protocol_port" : 86, "protocol" : "TERMINATED_HTTPS", "description" : null, "default_tls_container_ref" : "ad9b123e858d4652b80e89b9941e49a4", "admin_state_up" : true, "loadbalancers" : [ { "id" : "309a0f61-0b62-45f2-97d1-742f3434338e" } ], "member_timeout" : 60, "client_timeout" : 60, "keepalive_timeout" : 15, "client_ca_tls_container_ref" : "7875ccb4c6b44cdb90ab2ab89892ab71", "project_id" : "99a3fff0d03c428eac3678da6a7d0f24", "sni_container_refs" : [ "7f41c96223d34ebaa3c8e836b6625ec0" ], "connection_limit" : -1, "default_pool_id" : "5e7e0175-d5d5-4f37-bfba-88a9524ad20b", "tls_ciphers_policy" : "tls-1-0", "tags" : [ ], "created_at" : "2019-03-22T23:37:14Z", "updated_at" : "2019-03-22T23:37:14Z", "http2_enable" : false, "ipgroup" : null, "insert_headers" : { "X-Forwarded-ELB-IP" : true }, "transparent_client_ip_enable" : false, "quic_config" : null } ], "page_info" : { "next_marker" : "0b455839-3ea7-4bac-ad26-35bf22f96ea4", "previous_marker" : "0b11747a-b139-492f-9692-2df0b1c87193", "current_count" : 2 }, "request_id" : "774640ee-6863-4de3-8156-aff16f51a087" }
Status Codes
Status Code |
Description |
---|---|
200 |
Successful request. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot