GetListenerAttribute API Reference for ALB Listeners - Application Load Balancer - Alibaba Cloud - Server Load Balancer

Queries the details of a listener.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

alb:GetListenerAttribute

get

*LoadBalancer

acs:alb:{#regionId}:{#accountId}:loadbalancer/{#loadbalancerId}

acs:ResourceTag

None

Request parameters

Parameter	Type	Required	Description	Example
ListenerId	string	Yes	The listener ID.	lsn-o4u54y73wq7b******

Response elements

Element	Type	Description	Example
	object	The detailed information about the listener.
AclConfig	object	The ACL configuration structure.
AclRelations	array<object>	The IDs of the access control policies associated with the listener.
	object	The structure of the access control policies associated with the listener.
AclId	string	The ID of the access control policy associated with the listener.	acl-doc****
Status	string	The association status between the ACL and the listener. Valid values: Associating: The ACL is being associated. Associated: The ACL is associated. Dissociating: The ACL is being dissociated.	Associating
AclType	string	The access control type. Valid values: White: Only requests from the IP addresses or CIDR blocks configured in the selected ACL are forwarded. A whitelist is applicable to scenarios where an application allows access only from specific IP addresses. Configuring a whitelist poses business risks. After a whitelist is configured, only requests from the IP addresses in the whitelist can access the load balancing listener. If you enable whitelist access but do not add any IP addresses to the ACL, the load balancing listener forwards all requests. Black: No requests from the IP addresses or CIDR blocks configured in the selected ACL are forwarded. A blacklist is applicable to scenarios where an application blocks access from specific IP addresses. If you enable blacklist access but do not add any IP addresses to the ACL, the load balancing listener forwards all requests.	White
CaCertificates	array<object>	The list of CA certificates.
	object
CertificateId	string	The ID of the CA certificate.	139a00*****
IsDefault	boolean	Specifies whether the certificate is the default certificate. Valid values: true: Yes. false: No.	true
Status	string	The status of the certificate.	Associated
CaEnabled	boolean	Specifies whether mutual authentication is enabled. Valid values: true: Yes. false: No.	false
Certificates	array<object>	The list of certificates.
	object	The certificate structure.
CertificateId	string	The ID of the certificate. Only server certificates are supported.	123157*******
DefaultActions	array<object>	The list of default rule actions.
	array<object>	The structure of the default rule action.
ForwardGroupConfig	object	The configuration of the forwarding action. This parameter takes effect only when the action type is ForwardGroup.
ServerGroupTuples	array<object>	The destination server groups for forwarding.
	object	The destination server groups for forwarding.
ServerGroupId	string	The ID of the destination server group.	sgp-i5qt20******
Type	string	The action type. Valid value: ForwardGroup, which indicates that requests are forwarded to multiple server groups.	ForwardGroup
GzipEnabled	boolean	Specifies whether Gzip compression is enabled to compress specific file types. Valid values: true: Yes. false: No.	true
Http2Enabled	boolean	Specifies whether HTTP/2 is enabled. Valid values: true: Yes. false: No. Note This parameter is supported only by HTTPS listeners.	true
IdleTimeout	integer	Specifies the idle connection timeout period. Unit: seconds. If no request is received within the timeout period, the load balancer temporarily closes the current connection and establishes a new connection when the next request arrives.	2
ListenerDescription	string	The custom name of the listener.	HTTP_80
ListenerId	string	The listener ID.	lsn-o4u54y73wq7b******
ListenerPort	integer	The frontend port used by the load balancer.	80
ListenerProtocol	string	The listener protocol. Valid values: HTTP, HTTPS, and QUIC.	HTTP
ListenerStatus	string	The current 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.	Running
LoadBalancerId	string	The ID of the ALB instance.	alb-bd6oylbckp6k9x****
LogConfig	object	The log configuration information.
AccessLogRecordCustomizedHeadersEnabled	boolean	Specifies whether custom header fields are included in access logs. Valid values: true: Yes. false: No.	true
AccessLogTracingConfig	object	The Xtrace configuration information for access logs.
TracingEnabled	boolean	The status of the Xtrace feature. Valid values: true: Yes. false: No. Note You can set this parameter to true only when the access log feature (AccessLogEnabled) is enabled for the instance.	true
TracingSample	integer	The sampling rate for Xtrace. Valid values: 1 to 10000. Note This parameter takes effect only when TracingEnabled is set to true.	100
TracingType	string	The Xtrace type. Valid value: Zipkin. Note This parameter takes effect only when TracingEnabled is set to true.	Zipkin
QuicConfig	object	The configuration information for associating a QUIC listener.
QuicListenerId	string	The ID of the QUIC listener to be associated. This parameter is required when QuicUpgradeEnabled is set to true. This parameter takes effect only for HTTPS listeners. Note The original listener and the associated QUIC listener must belong to the same ALB instance, and the QUIC listener must not have been associated before.	lsn-ek6ad66t****
QuicUpgradeEnabled	boolean	Specifies whether QUIC upgrade is enabled. Valid values: true: Yes. false: No. Note This parameter takes effect only for HTTPS listeners.	true
RequestId	string	The request ID.	365F4154-92F6-4AE4-92F8-7FF******
RequestTimeout	integer	Specifies the request timeout period. Unit: seconds. If a backend server does not send a response within the timeout period, the load balancer stops waiting and returns an `HTTP 504` error code to the client.	34
SecurityPolicyId	string	The security policy. Note This parameter is supported only by HTTPS listeners.	tls_cipher_policy_1_1
Tags	array<object>	The tags.
	object	The tag structure.
Key	string	The tag key. It can be up to 128 characters in length and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	env
Value	string	The tag value. It can be up to 128 characters in length and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	product
XForwardedForConfig	object	The X-Forwarded-For field configuration.
XForwardedForClientCertClientVerifyAlias	string	The custom header name. This parameter takes effect only when XForwardedForClientCertClientVerifyEnabled is set to true. The name must be 1 to 40 characters in length and can contain lowercase letters, hyphens (-), underscores (_), and digits. Note This parameter is supported only by HTTPS listeners.	test_client-verify-alias_123456
XForwardedForClientCertClientVerifyEnabled	boolean	Specifies whether to use the `X-Forwarded-Clientcert-clientverify` header field to retrieve the verification result of the client certificate that accesses the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported only by HTTPS listeners.	true
XForwardedForClientCertFingerprintAlias	string	The custom header name. This parameter takes effect only when XForwardedForClientCertFingerprintEnabled is set to true. The name must be 1 to 40 characters in length and can contain lowercase letters, hyphens (-), underscores (_), and digits. Note This parameter is supported only by HTTPS listeners.	test_finger-print-alias_123456
XForwardedForClientCertFingerprintEnabled	boolean	Specifies whether to use the `X-Forwarded-Clientcert-fingerprint` header field to retrieve the fingerprint of the client certificate that accesses the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported only by HTTPS listeners.	true
XForwardedForClientCertIssuerDNAlias	string	The custom header name. This parameter takes effect only when XForwardedForClientCertIssuerDNEnabled is set to true. The name must be 1 to 40 characters in length and can contain lowercase letters, hyphens (-), underscores (_), and digits. Note This parameter is supported only by HTTPS listeners.	test_issue-dn-alias_123456
XForwardedForClientCertIssuerDNEnabled	boolean	Specifies whether to use the `X-Forwarded-Clientcert-issuerdn` header field to retrieve the issuer information of the client certificate that accesses the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported only by HTTPS listeners.	true
XForwardedForClientCertSubjectDNAlias	string	The custom header name. This parameter takes effect only when XForwardedForClientCertSubjectDNEnabled is set to true. The name must be 1 to 40 characters in length and can contain lowercase letters, hyphens (-), underscores (_), and digits. Note This parameter is supported only by HTTPS listeners.	test_subject-dn-alias_123456
XForwardedForClientCertSubjectDNEnabled	boolean	Specifies whether to use the `X-Forwarded-Clientcert-subjectdn` header field to retrieve the subject information of the client certificate that accesses the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported only by HTTPS listeners.	true
XForwardedForClientSourceIpsEnabled	boolean	Specifies whether to allow Application Load Balancer (ALB) to retrieve the actual client IP address from the `X-Forwarded-For` header field. Valid values: true: Yes. false: No. Note This parameter is supported by HTTP and HTTPS listeners.	false
XForwardedForClientSourceIpsTrusted	string	The trusted proxy IP addresses. Application Load Balancing (ALB) traverses the `X-Forwarded-For` header field from back to front and selects the first IP address that is not in the trusted IP address list as the actual client IP address. This IP address is used for source IP address-based rate limiting.	10.1.1.0/24
XForwardedForClientSrcPortEnabled	boolean	Specifies whether to use the `X-Forwarded-Client-Port` header field to retrieve the port of the client that accesses the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported by HTTP and HTTPS listeners.	true
XForwardedForEnabled	boolean	Specifies whether to use the `X-Forwarded-For` header field to retrieve the actual IP address of the client. Valid values: true (default): Yes. false: No. Note If you set this parameter to true, the default value of XForwardedForProcessingMode is append, and you can change it to remove. If you set this parameter to false, the `X-Forwarded-For` header field is retained without additional processing before the request is forwarded to the backend server. This parameter is supported by HTTP and HTTPS listeners.	true
XForwardedForHostEnabled	boolean	Specifies whether to use the `X-Forwarded-Host` header field to retrieve the domain name of the client that accesses the load balancing instance. Valid values: true: Yes. false (default): No. Note This parameter is supported by HTTP, HTTPS, and QUIC listeners.	false
XForwardedForProcessingMode	string	The processing mode for the `X-Forwarded-For` header field. This parameter takes effect only when XForwardedForEnabled is set to true. Valid values: append (default): Appends the IP address of the last hop to the `X-Forwarded-For` header field before the request is forwarded to the backend server. remove: Deletes the `X-Forwarded-For` header field before the request is forwarded to the backend server, regardless of whether the request contains the `X-Forwarded-For` header field. Note If you set this parameter to append, the IP address of the last hop is added to the `X-Forwarded-For` header field before the request is forwarded to the backend server. If you set this parameter to remove, the `X-Forwarded-For` header field is deleted before the request is forwarded to the backend server, regardless of whether the request contains the `X-Forwarded-For` header field. This parameter is supported by HTTP and HTTPS listeners.	append
XForwardedForProtoEnabled	boolean	Specifies whether to use the `X-Forwarded-Proto` header field to retrieve the listener protocol of the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported by HTTP, HTTPS, and QUIC listeners.	true
XForwardedForSLBIdEnabled	boolean	Specifies whether to use the `SLB-ID` header field to retrieve the load balancing instance ID. Valid values: true: Yes. false: No. Note This parameter is supported by HTTP, HTTPS, and QUIC listeners.	true
XForwardedForSLBPortEnabled	boolean	Specifies whether to use the `X-Forwarded-Port` header field to retrieve the listener port of the load balancing instance. Valid values: true: Yes. false: No. Note This parameter is supported by HTTP, HTTPS, and QUIC listeners.	true

Examples

Success response

JSON format

{
  "AclConfig": {
    "AclRelations": [
      {
        "AclId": "acl-doc****",
        "Status": "Associating"
      }
    ],
    "AclType": "White"
  },
  "CaCertificates": [
    {
      "CertificateId": "139a00*****",
      "IsDefault": true,
      "Status": "Associated"
    }
  ],
  "CaEnabled": false,
  "Certificates": [
    {
      "CertificateId": "123157*******"
    }
  ],
  "DefaultActions": [
    {
      "ForwardGroupConfig": {
        "ServerGroupTuples": [
          {
            "ServerGroupId": "sgp-i5qt20******"
          }
        ]
      },
      "Type": "ForwardGroup"
    }
  ],
  "GzipEnabled": true,
  "Http2Enabled": true,
  "IdleTimeout": 2,
  "ListenerDescription": "HTTP_80",
  "ListenerId": "lsn-o4u54y73wq7b******",
  "ListenerPort": 80,
  "ListenerProtocol": "HTTP",
  "ListenerStatus": "Running",
  "LoadBalancerId": "alb-bd6oylbckp6k9x****",
  "LogConfig": {
    "AccessLogRecordCustomizedHeadersEnabled": true,
    "AccessLogTracingConfig": {
      "TracingEnabled": true,
      "TracingSample": 100,
      "TracingType": "Zipkin"
    }
  },
  "QuicConfig": {
    "QuicListenerId": "lsn-ek6ad66t****",
    "QuicUpgradeEnabled": true
  },
  "RequestId": "365F4154-92F6-4AE4-92F8-7FF******",
  "RequestTimeout": 34,
  "SecurityPolicyId": "tls_cipher_policy_1_1",
  "Tags": [
    {
      "Key": "env",
      "Value": "product"
    }
  ],
  "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,
    "XForwardedForClientSourceIpsEnabled": false,
    "XForwardedForClientSourceIpsTrusted": "10.1.1.0/24",
    "XForwardedForClientSrcPortEnabled": true,
    "XForwardedForEnabled": true,
    "XForwardedForHostEnabled": false,
    "XForwardedForProcessingMode": "append",
    "XForwardedForProtoEnabled": true,
    "XForwardedForSLBIdEnabled": true,
    "XForwardedForSLBPortEnabled": true
  }
}

Error codes

HTTP status code	Error code	Error message	Description
403	Forbidden.LoadBalancer	Authentication is failed for %s.	Authentication is failed for %s.
404	ResourceNotFound.Listener	The specified resource %s is not found.	The listener does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.