Help Center/ Elastic Load Balance/ API Reference/ APIs (V3)/ Listener/ Viewing the Details of a Listener
Updated on 2025-09-22 GMT+08:00

Viewing the Details of a Listener

Function

This API is used to view the details of a listener.

Calling Method

For details, see Calling APIs.

URI

GET /v3/{project_id}/elb/listeners/{listener_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition: Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID.

Constraints: N/A

Range: The value can contain a maximum of 32 characters, including digits and lowercase letters.

Default value: N/A

listener_id

Yes

String

Definition: Specifies the listener ID.

Constraints: N/A

Range: N/A

Default value: N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition: Specifies the token used for IAM authentication.

Constraints:N/A

Range: N/A

Default value: N/A

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

request_id

String

Definition: Specifies the request ID.

Range: The value is automatically generated, and can contain characters including digits, lowercase letters, and hyphens (-).

listener

Listener object

Definition: Specifies the listener.

Table 4 Listener

Parameter

Type

Description

admin_state_up

Boolean

Definition: Specifies the administrative status of the listener.

Default value: true

client_ca_tls_container_ref

String

Definition: Specifies the ID of the CA certificate used by the listener. This parameter is available only when type is set to client.

Default value: N/A

connection_limit

Integer

Definition: Specifies the maximum number of connections that the listener can establish with backend servers.

Range: an integer greater than or equal to -1

created_at

String

Definition: Specifies the time when the listener was created.

Range: N/A

The value must be in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z.

default_pool_id

String

Definition: Specifies the ID of the default backend server group of the listener. If there is no matched forwarding policy, requests will be routed to the default backend server group.

Range: N/A

default_tls_container_ref

String

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

Default value: N/A

description

String

Definition: Provides supplementary information about the listener.

Range: N/A

http2_enable

Boolean

Definition: Specifies whether to allow clients to use HTTP/2 to communicate with the load balancer for higher access performance.

However, the load balancer still uses HTTP/1.x to forward requests to the backend server.

Range: N/A

id

String

Definition: Specifies the listener ID.

Range: N/A

insert_headers

ListenerInsertHeaders object

Definition: Specifies the HTTP headers that can transmit required information to backend servers. For example, you can use the X-Forwarded-ELB-IP header to transmit the load balancer EIP to backend servers.

loadbalancers

Array of LoadBalancerRef objects

Definition: Specifies the ID of the load balancer that the listener is added to. A listener can be associated with only one load balancer.

name

String

Definition: Specifies the name of the listener. If you leave the listener name empty, you cannot locate it in the listener list and view its details.

Range: N/A

project_id

String

Definition: Specifies the ID of the project that the listener belongs to.

Range: N/A

enterprise_project_id

String

Definition: Specifies the enterprise project ID.

Range: N/A

protocol

String

Definition: Specifies the protocol of the listener.

Range: TCP, UDP, HTTP, HTTPS, TERMINATED_HTTPS, QUIC, or TLS.

protocol_port

Integer

Definition: Specifies the port used by the listener.

Default value: N/A

sni_container_refs

Array of strings

Definition: Specifies the IDs of SNI certificates (server certificates with domain names) used by the listener.

Range: N/A

sni_match_algo

String

Definition: Specifies how wildcard domain name matches with the SNI certificates used by the listener.

Range: longest_suffix indicates longest suffix match. wildcard indicates wildcard match.

tags

Array of Tag objects

Definition: Lists the tags.

updated_at

String

Definition: Specifies the time when the listener was updated.

Range: The value must be in the format of yyyy-MM-dd''T''HH:mm:ss''Z'', for example, 2021-07-30T12:03:44Z.

tls_ciphers_policy

String

Definition: Specifies the security policy used by the listener.

Range: tls-1-0-inherit, tls-1-0, tls-1-1, tls-1-2, tls-1-2-strict, tls-1-2-fs, tls-1-0-with-1-3, tls-1-2-fs-with-1-3, hybrid-policy-1-0, or tls-1-2-strict-no-cbc. The default value is tls-1-2.

security_policy_id

String

Definition: Specifies the ID of the custom security policy.

Range: N/A

enable_member_retry

Boolean

Definition: Specifies whether to enable health check retries for backend servers.

Range: true indicates health check retries will be enabled. false indicates health check retries will be disabled.

keepalive_timeout

Integer

Definition: Specifies the idle timeout duration, in seconds. If the load balancer receives no requests within the idle timeout duration, it will disconnect the connection with the client and establish a new connection when there is a new request.

Range:

  • For TCP listeners, the value ranges from 10s to 4000s.

  • For HTTP, HTTPS, and TERMINATED_HTTPS listeners, the value ranges from 0s to 4000s.

client_timeout

Integer

Definition: Specifies the timeout duration for waiting for a response from a client, in seconds. There are two situations:

  • If the client fails to send a request header to the load balancer within the timeout duration, the request will be interrupted.

  • If the interval between two consecutive request bodies reaching the load balancer is greater than the timeout duration, the connection will be disconnected.

Range: 1-300

member_timeout

Integer

Definition: 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.

Range: 1-300

ipgroup

ListenerIpGroup object

Definition: Specifies the IP address group associated with the listener.

transparent_client_ip_enable

Boolean

Definition: Specifies whether to pass source IP addresses of the clients to backend servers. If it is enabled, the source IP addresses of the clients will be passed to the backend server.

This parameter applies only to TCP/UDP listeners added to a shared load balancer.

Range:

  • TCP or UDP listeners of shared load balancers: The value can be true or false, and the default value is false if this parameter is not passed.

  • HTTP or HTTPS listeners of shared load balancers: The value can only be true, and the default value is true if this parameter is not passed.

  • All listeners of dedicated load balancers: The value can only be true, and the default value is true if this parameter is not passed.

proxy_protocol_enable

Boolean

Definition: Specifies whether to enable ProxyProtocol 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.

Range: The value can be true (enable this option) or false (disable this option).

enhance_l7policy_enable

Boolean

Definition: Specifies whether to enable advanced forwarding. If advanced forwarding is enabled, more flexible forwarding policies and rules are supported.

The following scenarios are supported:

  • action can be set to REDIRECT_TO_URL (requests will be redirected to another URL) or Fixed_RESPONSE (a fixed response body will be returned to clients).

  • Parameters priority, redirect_url_config, and fixed_response_config can be specified in a forwarding policy.

  • type can be set to METHOD, HEADER, QUERY_STRING, or SOURCE_IP for a forwarding rule.

  • If type is set to HOST_NAME for a forwarding rule, the value of the forwarding rule supports wildcard asterisks (*).

  • Parameter conditions can be specified for forwarding rules.

Range: The value can be true (enable this option) or false (disable this option).

quic_config

ListenerQuicConfig object

Definition: Specifies the QUIC configuration for the current listener.

protection_status

String

Definition: Specifies the protection status.

Range:

  • nonProtection: The resource is not protected.

  • consoleProtection: Modification is not allowed on the console.

protection_reason

String

Definition: Specifies why modification protection is enabled.

Range: The value can contain a maximum of 255 Unicode characters, excluding angle brackets (<>).

gzip_enable

Boolean

Definition: Specifies whether to enable gzip_enable for a load balancer.

Range: The value can be true (enable this option) or false (disable this option).

port_ranges

Array of PortRange objects

Definition: Specifies one or more port ranges, including the start and end ports.

ssl_early_data_enable

Boolean

Definition: Specifies whether to enable zero round trip time resumption (0-RTT) for listeners.

Constraints: This option can be configured only for HTTPS listeners and depends on the TLS 1.3 security policy protocols.

cps

Integer

Definition: Specifies the maximum number of new connections that a listener can handle per second. If the value is greater than the number defined in the load balancer flavors, the latter is used as the limit.

Range: 0 to 1000000

connection

Integer

Definition: Specifies the maximum number of concurrent connections that a listener can handle per second. If the value is greater than the number defined in the load balancer flavors, the latter is used as the limit.

Range: 0 to 1000000

nat64_enable

Boolean

Definition: Specifies whether to translate between IPv4 and IPv6 addresses. This option allows a client to access IPv4 or IPv6 backend servers by accessing the IPv4 or IPv6 address of a load balancer.

Range:

true: Enable nat64_enable.

false: Disable nat64_enable.

Table 5 ListenerInsertHeaders

Parameter

Type

Description

X-Forwarded-ELB-IP

Boolean

Definition: If X-Forwarded-ELB-IP is set to true, the load balancer EIP will be stored in the X-Forwarded-ELB-IP header and passed to backend servers.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-Port

Boolean

Definition: If X-Forwarded-Port is set to true, the listening port of the load balancer will be stored in the X-Forwarded-Port header and passed to backend servers.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-For-Port

Boolean

Definition: 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.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-Host

Boolean

Definition: If X-Forwarded-Host is set to true, the client host can be stored in the X-Forwarded-Host header and passed to backend servers.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-Proto

Boolean

Definition: If X-Forwarded-Proto is set to true, the listener protocol of the load balancer can be stored in the X-Forwarded-Proto header and passed to backend servers.

Constraints: N/A

Range: N/A

Default value: N/A

X-Real-IP

Boolean

Definition: If X-Real-IP is set to true, the client IP address can be stored in the X-Real-IP header and passed to backend servers.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-ELB-ID

Boolean

Definition: If X-Forwarded-ELB-ID is set to true, the load balancer ID can be transferred to backend servers through the X-Forwarded-ELB-ID header.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-TLS-Certificate-ID

Boolean

Definition: 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 X-Forwarded-TLS-Certificate-ID header.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-TLS-Protocol

Boolean

Definition: If X-Forwarded-TLS-Protocol is set to true, the algorithm protocol of the load balancer can be transferred to backend servers through the X-Forwarded-TLS-Protocol header.

Constraints: N/A

Range: N/A

Default value: N/A

X-Forwarded-TLS-Cipher

Boolean

Definition: If X-Forwarded-TLS-Cipher is set to true, the algorithm suite of the load balancer can be transferred to backend servers through the X-Forwarded-TLS-Cipher header.

Constraints: N/A

Range: N/A

Default value: N/A

Table 6 LoadBalancerRef

Parameter

Type

Description

id

String

Definition: Specifies the load balancer ID.

Range: N/A

Table 7 Tag

Parameter

Type

Description

key

String

Definition: Specifies the tag key.

Range: N/A

value

String

Definition: Specifies the tag value.

Range: N/A

Table 8 ListenerIpGroup

Parameter

Type

Description

ipgroup_id

String

Definition: Specifies the ID of the IP address group associated with the listener.

This parameter is mandatory during creation and is optional during update.

Constraints:

The specified IP address group must exist, and the value cannot be null. Otherwise, the IP address group conflicts with enable_ipgroup.

enable_ipgroup

Boolean

Definition: Specifies whether access control is enabled.

A listener with access control enabled can be directly deleted.

Range:

  • true: Access control is enabled.

  • false: Access control is disabled.

type

String

Definition: Specifies how access to the listener is controlled.

Range:

  • white: A whitelist will be configured. Only IP addresses in the whitelist can access the listener.

  • black: A blacklist will be configured. IP addresses in the blacklist are not allowed to access the listener.

Table 9 ListenerQuicConfig

Parameter

Type

Description

quic_listener_id

String

Definition: Specifies the ID of the QUIC listener.

Range: N/A

enable_quic_upgrade

Boolean

Definition: Specifies whether to enable QUIC upgrade. If this option is enabled, HTTPS listeners will be upgraded to QUIC listeners.

Range:

  • True: Enable QUIC upgrade.

  • False: Disable QUIC upgrade.

Table 10 PortRange

Parameter

Type

Description

start_port

Integer

Definition: Specifies the start port number.

Constraints: N/A

Range: 1-65535

Default value: N/A

end_port

Integer

Definition: Specifies the end port number. The value must be greater than or equal to the start port number.

Constraints: N/A

Range: 1-65535

Default value: N/A

Example Requests

Viewing the details of a listener

GET https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/listeners/0b11747a-b139-492f-9692-2df0b1c87193

Example Responses

Status code: 200

Successful request.

{
  "listener" : {
    "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,
    "nat64_enable" : false
  },
  "request_id" : "1394eb39-e4c8-4177-b96d-aaff569f1833"
}

SDK Sample Code

The SDK sample code is as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.elb.v3.region.ElbRegion;
import com.huaweicloud.sdk.elb.v3.*;
import com.huaweicloud.sdk.elb.v3.model.*;


public class ShowListenerSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        ElbClient client = ElbClient.newBuilder()
                .withCredential(auth)
                .withRegion(ElbRegion.valueOf("<YOUR REGION>"))
                .build();
        ShowListenerRequest request = new ShowListenerRequest();
        request.withListenerId("{listener_id}");
        try {
            ShowListenerResponse response = client.showListener(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkelb.v3.region.elb_region import ElbRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkelb.v3 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = ElbClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(ElbRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ShowListenerRequest()
        request.listener_id = "{listener_id}"
        response = client.show_listener(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    elb "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/elb/v3"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/elb/v3/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/elb/v3/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        Build()

    client := elb.NewElbClient(
        elb.ElbClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.ShowListenerRequest{}
	request.ListenerId = "{listener_id}"
	response, err := client.ShowListener(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

Successful request.

Error Codes

See Error Codes.