Queries listeners.

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 token that is used for the next query. Valid values:

  • If this your first query or no next query is to be sent, ignore this parameter.
  • If a next query is to be sent, set the value to the value of NextToken that is returned from the last call.
MaxResults Integer No 50

The maximum number of entries to return. This parameter is optional. Valid values: 1 to 100. If this parameter is not set, the default value 20 is used.

ListenerIds Array of String No lsr-bp1bpn0kn908w4nbw****

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

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

The IDs of the Application Load Balancer (ALB) instances. You can specify at most 20 IDs.

ListenerProtocol String No HTTP

The listening protocol. Valid values:

  • HTTP
  • HTTPS
  • QUIC

Response parameters

Parameter Type Example Description
Listeners Array of listener

The list of listeners.

DefaultActions Array of defaultAction

The actions of the default forwarding rule.

ForwardGroupConfig Object

The configuration of the forwarding rule action. This parameter is required and takes effect only when the type of the action is FowardGroup.

ServerGroupTuples Array of serverGroupTuple

The server groups to which requests are forwarded.

ServerGroupId String rsp-cige6j****

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

Type String ForwardGroup

The type of the action. If the type of the action is ForwardGroup, it indicates that requests are forwarded to multiple vServer groups.

GzipEnabled Boolean false

Indicates whether gzip compression is enabled to compress specific types of files. Valid values:

  • true: yes
  • false: no
Http2Enabled Boolean false

Indicates whether HTTP/2 is enabled. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
IdleTimeout Integer 3

The timeout period of an idle connection. Unit: seconds. Valid values: 1 to 60.

If no request is received within the specified timeout period, ALB closes the connection. ALB establishes the connection again 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 IDs of the listeners.

ListenerPort Integer 80

The frontend port that is used by the ALB instance. Valid values: 1 to 65535.

ListenerProtocol String HTTP

The listening protocol. Valid values:

  • HTTP
  • HTTPS
  • QUIC
ListenerStatus String Running

The status 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 stopped.
LoadBalancerId String lb-bp1b6c719dfa08ex*****

The ID of the ALB instance.

LogConfig Object

The log configuration.

AccessLogRecordCustomizedHeadersEnabled Boolean true

Indicates whether custom headers are carried in the access log. Valid values:

  • true: yes
  • false: no
AccessLogTracingConfig Object

The configuration of Xtrace. Xtrace is used to record the requests sent to ALB.

TracingEnabled Boolean true

Indicates whether Xtrace is enabled. Valid values:

  • true: yes
  • false: no
Note This parameter can be set to true only when the access log feature of ALB is enabled by specifying AccessLogEnabled.
TracingSample Integer 100

The sampling rate of Xtrace. Valid values: 1 to 10000.

Note This parameter takes effect when TracingEnabled is set to true.
TracingType String Zipkin

The Xtrace type. This parameter can be set to Zipkin.

Note This parameter takes effect when TracingEnabled is set to true.
QuicConfig Object

The configuration information when the listener is associated with a QUIC listener.

QuicListenerId String lsr-bp1bpn908w4nbw****

The ID of the QUIC listener. This parameter is required if the QuicUpgradeEnabled parameter is set to true. Only HTTPS listeners support this parameter.

Note The HTTPS listener and the associated QUIC listener must be added to the same ALB instance. In addition, make sure that the QUIC listener is not associated with another listener.
QuicUpgradeEnabled Boolean true

Indicates whether QUIC upgrade is enabled. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
RequestTimeout Integer 34

The timeout period of a request. Unit: seconds. Valid values: 1 to 180.

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

SecurityPolicyId String tls_cipher_policy_1_1

The security policy.

Note Only HTTPS listeners support this parameter.
XForwardedForConfig Object

Configuration of the XForward header.

XForwardedForClientCertClientVerifyAlias String test_client-verify-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertClientVerifyEnabled is set to true.

The name is 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 is used to obtain the verification result of the client certificate. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertFingerprintAlias String test_finger-print-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertFingerprintEnabled is set to true.

The name is 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 is used to obtain the fingerprint of the client certificate. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertIssuerDNAlias String test_issue-dn-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true.

The name is 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 header is used to obtain information about the authority that issues the client certificate. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
XForwardedForClientCertSubjectDNAlias String test_subject-dn-alias_123456

The name of the custom header. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true.

The name is 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 is used to obtain information about the owner of the client certificate. Valid values:

  • true: yes
  • false: no
Note Only HTTPS listeners support this parameter.
XForwardedForClientSrcPortEnabled Boolean true

Indicates whether the X-Forwarded-Client-Port header is used to obtain the client port. Valid values:

  • true: yes
  • false: no
Note HTTP and HTTPS listeners support this parameter.
XForwardedForEnabled Boolean true

Indicates whether the X-Forwarded-For header is used to retrieve client IP addresses. Valid values:

  • true: yes
  • false: no
Note HTTP and HTTPS listeners support this parameter.
XForwardedForProtoEnabled Boolean true

Indicates whether the X-Forwarded-Proto header is used to retrieve the listening protocol. Valid values:

  • true: yes
  • false: no
Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBIdEnabled Boolean true

Indicates whether the SLB-ID header is used to retrieve the ID of the ALB instance. Valid values:

  • true: yes
  • false: no
Note HTTP, HTTPS, and QUIC listeners support this parameter.
XForwardedForSLBPortEnabled Boolean true

Indicates whether the X-Forwarded-Port header is used to obtain the listening port of the ALB instance. Valid values:

  • true: yes
  • false: no
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 this parameter is not returned, 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 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>Running</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" : "Running",
    "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.