Queries the listeners that are configured for Application Load Balancer (ALB) instances.

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 ListListeners

The operation that you want to perform.

Set the value to ListListeners.

NextToken String No FFmyTO70tTpLG6I3FmYAXGKPd****

The position where the query starts. If this parameter is left empty, the query starts from the beginning.

MaxResults Integer No 50

The maximum number of entries to return.

Valid values: 1 to 100.

Default value: 20. This value indicates that this parameter is not set.

Note This parameter is optional.
ListenerIds Array of String No lsr-bp1bpn0kn908w4nbw****

The IDs of the listeners.You can specify at most 20 listener IDs.

LoadBalancerIds Array of String No lb-bp1b6c719dfa08ex*****

The IDs of the ALB instances. You can specify at most 20 IDs.

ListenerProtocol String No HTTP

The listener protocol that you want to filter.

Valid values: HTTP, HTTPS, and QUIC.

Response parameters

Parameter Type Example Description
Listeners Array of listener

The list of listeners.

DefaultActions Array of defaultAction

The list of default actions.

ForwardGroupConfig Object

The configuration of the forwarding rule action. This parameter is required if the Type parameter is set to FowardGroup.

ServerGroupTuples Array of serverGroupTuple

The destination server group to which requests are forwarded.

ServerGroupId String rsp-cige6j****

The ID of the destination server group to which requests are forwarded.

Type String ForwardGroup

The action type.

The value is set to ForwardGroup. It indicates that requests are forwarded to multiple vServer groups.

GzipEnabled Boolean false

Indicates whether gzip compression is enabled to compress files of a specific type.

Valid values: true and false.

Default value: true.

Http2Enabled Boolean false

Indicates whether HTTP/2 is enabled. Default value: on.

Valid values: true and false.

Default value: true.

Note Only HTTPS listeners support this parameter.
IdleTimeout Integer 3

The timeout period of idle connections.

Valid values: 1 to 60. Unit: seconds.

Default value: 15.

If no request is received within the specified timeout period, ALB closes the connection. ALB recreates the connection when a new connection request is received.

ListenerDescription String test

The description of the listener. The description must be 2 to 256 characters in length.

ListenerId String lsr-bp1bpn0kn908w4nbw****

The ID of the listener.

ListenerPort Integer 80

The frontend port that is used by the ALB instance.

Valid values: 1 to 65535.

ListenerProtocol String HTTP

The listener protocol.

Valid values: HTTP,HTTPS, and QUIC.

ListenerStatus String active

The state of the listener. Valid values:

  • Provisioning: The listener is being created.
  • Running: The listener is running.
  • Configuring: The listener is being configured.
  • Stopped: The listener is being configured.
LoadBalancerId String lb-bp1b6c719dfa08ex*****

The ID of the ALB instance.

LogConfig Object

The log configuration.

AccessLogRecordCustomizedHeadersEnabled Boolean true

Indicates whether the access log has a custom header.

Valid values: true and false.

Default value: false.

AccessLogTracingConfig Object

The configuration of the Xtrace feature.

TracingEnabled Boolean true

The state of the Xtrace feature.

Valid values: true and false.

Default value: false.

Note You can set this parameter to true only if you set AccessLogEnabled to true.
TracingSample Integer 100

The sampling rate of the Xtrace feature.

Valid values: 1 to 10000.

Note If TracingEnabled is set to true, this parameter is valid.
TracingType String Zipkin

The type of Xtrace. Set the value to Zipkin.

Note If TracingEnabled is set to true, this parameter is valid.
QuicConfig Object

The configuration information when you specify to associate QUIC listeners.

QuicListenerId String lsr-bp1bpn908w4nbw****

The ID of the QUIC listener to be associated. If QuicUpgradeEnabled is set to true, this parameter is required. Only HTTPS listeners support this parameter.

Note The original listener and the QUIC listener must belong to the same ALB instance. In addition, make sure that the QUIC listener has not been associated before.
QuicUpgradeEnabled Boolean true

Indicates whether QUIC upgrade is enabled.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
RequestTimeout Integer 34

The timeout period of the request.

Valid values: 1 to 180. Unit: seconds.

Default value: 60.

If no response is received from the backend server within the specified timeout period, ALB sends an HTTP 504 status code to the client.

SecurityPolicyId String tls_cipher_policy_1_1

The security policy.

Note Only HTTPS listeners support this parameter.
XForwardedForConfig Object

The configuration of the XForward field.

XForwardedForClientCertClientVerifyAlias String test_client-verify-alias_123456

The name of the custom header. This parameter is valid only if XForwardedForClientCertClientVerifyEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-) and underscores (_).

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertClientVerifyEnabled Boolean true

Indicates whether the X-Forwarded-Clientcert-clientverify header field is used to obtain the verification result of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintAlias String test_finger-print-alias_123456

The name of the custom header. This parameter is valid only if XForwardedForClientCertFingerprintEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-) and underscores (_).

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintEnabled Boolean true

Indicates whether the X-Forwarded-Clientcert-fingerprint header field is used to obtain the fingerprint of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNAlias String test_issue-dn-alias_123456

The name of the custom header. This parameter is valid only if XForwardedForClientCertIssuerDNEnabled is set to On.

The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-) and underscores (_).

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNEnabled Boolean true

Indicates whether the X-Forwarded-Clientcert-issuerdn is used to obtain information about the authority that issues the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNAlias String test_subject-dn-alias_123456

The name of the custom header. This parameter is valid only if XForwardedForClientCertSubjectDNEnabled is set to true.

The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-) and underscores (_).

Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNEnabled Boolean true

Indicates whether the X-Forwarded-Clientcert-subjectdn header field is used to obtain information about the owner of the ALB client certificate.

Valid values: true and false.

Default value: false.

Note Only HTTPS listeners support this parameter.
XForwardedForClientSrcPortEnabled Boolean true

Indicates whether the X-Forwarded-Client-Port header field is used to obtain the port of the ALB client.

Valid values: true and false.

Default value: false.

Note HTTP and HTTPS listeners support this parameter.
XForwardedForEnabled Boolean true

Indicates whether the X-Forwarded-For header field is used to obtain the real IP address of tqhe client.

Valid values: true and false.

Default value: true.

Note HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean true

Indicates whether the X-Forwarded-Proto header field is used to obtain the listener protocol of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBIdEnabled Boolean true

Indicates whether the SLB-ID header field is used to obtain the ID of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBPortEnabled Boolean true

Indicates whether the X-Forwarded-Port header field is used to obtain the listener port of the ALB instance.

Valid values: true and false.

Default value: false.

Note HTTP, HTTPS, and QUIC listeners support this parameter.
MaxResults Integer 50

The maximum number of entries returned.

NextToken String FFmyTO70tTpLG6I3FmYAXGKPd****

The position where the query stopped. If the response does not contain this parameter, all data has been queried.

RequestId String 365F4154-92F6-4AE4-92F8-7FF34B540710

The ID of the request.

TotalCount Integer 1000

The total number of entries returned.

Examples

Sample requests

http(s)://[Endpoint]/?Action=ListListeners
&NextToken=FFmyTO70tTpLG6I3FmYAXGKPd****
&MaxResults=50
&ListenerIds=["lsr-bp1bpn0kn908w4nbw****"]
&LoadBalancerIds=["lb-bp1b6c719dfa08ex*****"]
&ListenerProtocol=HTTP
&Common request parameters

Sample success responses

XML format

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

<ListListenersResponse>
    <Listeners>
        <DefaultActions>
            <ForwardGroupConfig>
                <ServerGroupTuples>
                    <ServerGroupId>rsp-cige6j****</ServerGroupId>
                </ServerGroupTuples>
            </ForwardGroupConfig>
            <Type>ForwardGroup</Type>
        </DefaultActions>
        <GzipEnabled>false</GzipEnabled>
        <Http2Enabled>false</Http2Enabled>
        <IdleTimeout>3</IdleTimeout>
        <ListenerDescription>test</ListenerDescription>
        <ListenerId>lsr-bp1bpn0kn908w4nbw****</ListenerId>
        <ListenerPort>80</ListenerPort>
        <ListenerProtocol>HTTP</ListenerProtocol>
        <ListenerStatus>active</ListenerStatus>
        <LoadBalancerId>lb-bp1b6c719dfa08ex*****</LoadBalancerId>
        <LogConfig>
            <AccessLogRecordCustomizedHeadersEnabled>true</AccessLogRecordCustomizedHeadersEnabled>
            <AccessLogTracingConfig>
                <TracingEnabled>true</TracingEnabled>
                <TracingSample>100</TracingSample>
                <TracingType>Zipkin</TracingType>
            </AccessLogTracingConfig>
        </LogConfig>
        <QuicConfig>
            <QuicListenerId>lsr-bp1bpn908w4nbw****</QuicListenerId>
            <QuicUpgradeEnabled>true</QuicUpgradeEnabled>
        </QuicConfig>
        <RequestTimeout>34</RequestTimeout>
        <SecurityPolicyId>tls_cipher_policy_1_1</SecurityPolicyId>
        <XForwardedForConfig>
            <XForwardedForClientCertClientVerifyAlias>test_client-verify-alias_123456</XForwardedForClientCertClientVerifyAlias>
            <XForwardedForClientCertClientVerifyEnabled>true</XForwardedForClientCertClientVerifyEnabled>
            <XForwardedForClientCertFingerprintAlias>test_finger-print-alias_123456</XForwardedForClientCertFingerprintAlias>
            <XForwardedForClientCertFingerprintEnabled>true</XForwardedForClientCertFingerprintEnabled>
            <XForwardedForClientCertIssuerDNAlias>test_issue-dn-alias_123456</XForwardedForClientCertIssuerDNAlias>
            <XForwardedForClientCertIssuerDNEnabled>true</XForwardedForClientCertIssuerDNEnabled>
            <XForwardedForClientCertSubjectDNAlias>test_subject-dn-alias_123456</XForwardedForClientCertSubjectDNAlias>
            <XForwardedForClientCertSubjectDNEnabled>true</XForwardedForClientCertSubjectDNEnabled>
            <XForwardedForClientSrcPortEnabled>true</XForwardedForClientSrcPortEnabled>
            <XForwardedForEnabled>true</XForwardedForEnabled>
            <XForwardedForProtoEnabled>true</XForwardedForProtoEnabled>
            <XForwardedForSLBIdEnabled>true</XForwardedForSLBIdEnabled>
            <XForwardedForSLBPortEnabled>true</XForwardedForSLBPortEnabled>
        </XForwardedForConfig>
    </Listeners>
    <MaxResults>50</MaxResults>
    <NextToken>FFmyTO70tTpLG6I3FmYAXGKPd****</NextToken>
    <RequestId>365F4154-92F6-4AE4-92F8-7FF34B540710</RequestId>
    <TotalCount>1000</TotalCount>
</ListListenersResponse>

JSON format

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

{
  "Listeners" : {
    "DefaultActions" : {
      "ForwardGroupConfig" : {
        "ServerGroupTuples" : {
          "ServerGroupId" : "rsp-cige6j****"
        }
      },
      "Type" : "ForwardGroup"
    },
    "GzipEnabled" : false,
    "Http2Enabled" : false,
    "IdleTimeout" : 3,
    "ListenerDescription" : "test",
    "ListenerId" : "lsr-bp1bpn0kn908w4nbw****",
    "ListenerPort" : 80,
    "ListenerProtocol" : "HTTP",
    "ListenerStatus" : "active",
    "LoadBalancerId" : "lb-bp1b6c719dfa08ex*****",
    "LogConfig" : {
      "AccessLogRecordCustomizedHeadersEnabled" : true,
      "AccessLogTracingConfig" : {
        "TracingEnabled" : true,
        "TracingSample" : 100,
        "TracingType" : "Zipkin"
      }
    },
    "QuicConfig" : {
      "QuicListenerId" : "lsr-bp1bpn908w4nbw****",
      "QuicUpgradeEnabled" : true
    },
    "RequestTimeout" : 34,
    "SecurityPolicyId" : "tls_cipher_policy_1_1",
    "XForwardedForConfig" : {
      "XForwardedForClientCertClientVerifyAlias" : "test_client-verify-alias_123456",
      "XForwardedForClientCertClientVerifyEnabled" : true,
      "XForwardedForClientCertFingerprintAlias" : "test_finger-print-alias_123456",
      "XForwardedForClientCertFingerprintEnabled" : true,
      "XForwardedForClientCertIssuerDNAlias" : "test_issue-dn-alias_123456",
      "XForwardedForClientCertIssuerDNEnabled" : true,
      "XForwardedForClientCertSubjectDNAlias" : "test_subject-dn-alias_123456",
      "XForwardedForClientCertSubjectDNEnabled" : true,
      "XForwardedForClientSrcPortEnabled" : true,
      "XForwardedForEnabled" : true,
      "XForwardedForProtoEnabled" : true,
      "XForwardedForSLBIdEnabled" : true,
      "XForwardedForSLBPortEnabled" : true
    }
  },
  "MaxResults" : 50,
  "NextToken" : "FFmyTO70tTpLG6I3FmYAXGKPd****",
  "RequestId" : "365F4154-92F6-4AE4-92F8-7FF34B540710",
  "TotalCount" : 1000
}

Error codes

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