# Describe Application Load Balancer Listener - DescribeListeners ## Overview Describe a specified listener or all listeners under an application type load balancing instance ## Definition ### Public Parameters | Parameter Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Action** | string | Corresponding API command name, the current API is `DescribeListeners`. | **Yes** | | **PublicKey** | string | The user's public key can be obtained from [Console](https://console.scloudsg.com/uaccount/api_manage) | **Yes** | | **Signature** | string | User signature generated based on public key and API command, see [Signature Algorithm](/docs/api/summary/signature.md) | **Yes** | ### Request Parameters | Parameter Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Region** | string | Region. See [List of Regions and Availability Zones](/docs/api/summary/regionlist) |**Yes**| | **ProjectId** | string | Project ID. If not filled in, the default project is used, sub-accounts must be filled in. Please refer to the [GetProjectList interface](/docs/api/summary/get_project_list). |**Yes**| | **ListenerId** | string | The ID of the application load balancer listener. If ListenerId is specified, LoadBalancerId is ignored. Either ListenId or LoadBalancerId must be selected. |No| | **LoadBalancerId** | string | The ID of the application load balancer instance. If ListenId is not specified, it describes all listeners under the specified LoadBalancerId. |No| | **Offset** | int | Data offset, default is 0 |No| | **Limit** | int | Data pagination value, default is 100 |No| ### Response Field | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **RetCode** | int | Return status code. If it is 0, it means successful return. If it is not 0, it means failure. |**Yes**| | **Action** | string | Operation command name. |**Yes**| | **Message** | string | Returns an error message, providing detailed description when `RetCode` is non-zero. |No| | **TotalCount** | int | Total number of load balancer listeners that meet the conditions |No| | **Listeners** | array[[*Listener*](#listener)] | Load Balancer Listener Information |No| #### Data Model #### Listener | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **ListenerId** | string | Listener's ID |No| | **Name** | string | Name of the Listener |No| | **Remark** | string | Remarks on the Listener |No| | **ListenerPort** | int | Listener's Listening Port |No| | **ListenerProtocol** | string | Monitoring Protocol. Application-specific limited values: HTTP, HTTPS. |No| | **Certificates** | array[[*Certificate*](#certificate)] | (Application-specific) Default server certificate ID. Only HTTPS listening is supported. For specific interface details, see Certificate. |No| | **SecurityPolicyId** | string | (Application-specific) Security policy group ID. Only HTTPS listening supports binding; Default -> Native policy |No| | **IdleTimeout** | int | Connection idle timeout. Unit: seconds. |No| | **Scheduler** | string | Load Balancing Algorithm. Application-specific limited values: Roundrobin -> Round Robin; Source -> Source Address; WeightRoundrobin -> Weighted Round Robin; Leastconn -> Least Connections; Backup -> Master-Slave Mode |No| | **StickinessConfig** | [*StickinessConfigSet*](#stickinessconfigset) | Configuration related to session persistence. For detailed structure, see StickinessConfigSet. |No| | **HealthCheckConfig** | [*HealthCheckConfigSet*](#healthcheckconfigset) | Configuration related to Health Check. For specific structure, see HealthCheckConfigSet. |No| | **CompressionEnabled** | boolean | (Application-specific) Whether to enable data compression function. Currently, only gzip is supported to compress specific file types. |No| | **HTTP2Enabled** | boolean | (Application-specific) Whether to enable the HTTP/2 feature. Only HTTPS listening supports enabling. |No| | **RedirectEnabled** | boolean | (Application-specific) Whether to enable HTTP redirection to HTTPS. Only HTTP listening supports enabling. |No| | **RedirectPort** | int | (Application-specific) Redirect Port |No| | **Targets** | array[[*Target*](#target)] | Information of the added service node. See Target for specific structure. |No| | **Rules** | array[[*Rule*](#rule)] | (Application-specific) Forwarding Rule Information |No| | **State** | string | Listener health status. Limited enumeration values: Healthy -> Healthy, Unhealthy -> Unhealthy, PartialHealth -> Partially Healthy, None -> No node status. |No| #### Certificate | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **SSLId** | string | Certificate ID |No| | **IsDefault** | boolean | Is it the default certificate? |No| #### StickinessConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Enabled** | boolean | Whether to enable the session persistence feature. The application load balancing instance is implemented based on Cookie. |No| | **Type** | string | (Application-specific) Cookie processing method. Limited enumeration values: ServerInsert -> Automatically generate KEY; UserDefined -> User-defined KEY. |No| | **CookieName** | string | (Application-specific) Custom Cookie. Effective when the StickinessType value is "UserDefined"."""
|No| #### HealthCheckConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Enabled** | boolean | Whether to enable the health check function. Temporarily does not support closing. The default value is: true |No| | **Type** | string | Health check method. Application type limited values: Port -> Port check; HTTP -> HTTP check; Default value: Port |No| | **Domain** | string | (Application-specific) HTTP check domain. This field is meaningful when Type is HTTP, representing the HTTP check domain. |No| | **Path** | string | (Application-specific) HTTP check path. This field is meaningful when the Type is HTTP, representing the HTTP check path. |No| | **Method** | string | (Application-specific) HTTP inspection method. This field is meaningful when Type is HTTP, representing the HTTP inspection method. |No| | **ResponseCode** | string | (Application-specific) GRPC check response code. This field is meaningful when Type is GRPC, representing the GRPC check response code. |No| #### Target | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **ResourceType** | string | The type of service node. Limited enumeration values: UHost -> Cloud Host, UNI -> Virtual Network Interface, UPM -> Physical Cloud Host, IP -> IP type; Default value: "UHost"; For non-IP types, if the resource has multiple IPs, only the main IP can be added; For non-IP types, related resource information will be displayed during the display, and only IP information will be displayed for IP types. When the related resource is deleted, the non-IP type will remove the related resource from lb, and the IP type does not guarantee this logic. |No| | **ResourceId** | string | Resource ID of the service node |No| | **ResourceName** | string | Resource Name of Service Node |No| | **VPCId** | string | Service node's VPC resource ID |No| | **SubnetId** | string | Subnet resource ID of the service node |No| | **ResourceIP** | string | IP of the service node |No| | **Port** | int | Port of the service node |No| | **Weight** | int | Weight of the service node. Only effective when the weighted round-robin algorithm is used. |No| | **Enabled** | boolean | Is the service node enabled? |No| | **IsBackup** | boolean | Is the service node a backup node? |No| | **Id** | string | The identification ID of the service node. Used in ALB/NLB, unrelated to the resource's own ID, can be used for UpdateTargetsAttribute/RemoveTargets. |No| | **State** | string | Health check status of the service node. Limited enumeration values: Healthy -> Healthy, Unhealthy -> Unhealthy |No| #### Rule | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **RuleId** | string | ID of the forwarding rule |No| | **RuleConditions** | array[[*RuleCondition*](#rulecondition)] | Forwarding rule matching conditions. See RuleCondition for specific structure. |No| | **RuleActions** | array[[*RuleAction*](#ruleaction)] | Forwarding action. For specific rules, see RuleAction. |No| | **IsDefault** | boolean | Is it the default forwarding rule? |No| | **Pass** | boolean | When the service node for forwarding is empty, should the rule be ignored? |No| #### RuleCondition | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Type** | string | Match condition type. Limited enumeration values: Host, Path |**Yes**| | **HostConfig** | [*HostConfigSet*](#hostconfigset) | Domain-related configuration. Required when Type is Host. See HostConfigSet for specific structure. |No| | **PathConfig** | [*PathConfigSet*](#pathconfigset) | Configuration related to the path. Required when Type is Path. For detailed structure, see PathConfigSet. |No| #### RuleAction | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Type** | string | Action type. Limited enumeration values: Forward, "InsertHeader", "Cors", "FixedResponse", "RemoveHeader" |**Yes**| | **ForwardConfig** | [*ForwardConfigSet*](#forwardconfigset) | Forward service node related configuration, corresponding to type value: "Forward". For specific structure, see ForwardConfigSet. |No| | **FixedResponseConfig** | [*FixedResponseConfigSet*](#fixedresponseconfigset) | Static return related configuration, corresponding to type value: "FixedResponse". For specific structure, see FixedResponseConfigSet |No| | **InsertHeaderConfig** | [*InsertHeaderConfigSet*](#insertheaderconfigset) | Insert header-related configuration, corresponding to the type value: "InsertHeader". For the specific structure, see InsertHeaderConfigSet. |No| | **CorsConfig** | [*CorsConfigSet*](#corsconfigset) | Configuration related to cross-domain, corresponding to type value: "Cors". For specific structure, see CorsConfigSet. |No| | **RemoveHeaderConfig** | [*RemoveHeaderConfigSet*](#removeheaderconfigset) | Delete header-related configuration, corresponding type value: "RemoveHeader". For specific structure, see RemoveHeaderConfigSet |No| | **Order** | int | The execution order of forwarding rule actions ranges from 1 to 1000, with actions executed from smallest to largest value. The value cannot be empty or duplicated.

Forward and FixedResponse types of actions do not consider Order and are executed last. |No| #### ForwardConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Targets** | array[[*ForwardTargetSet*](#forwardtargetset)] | The backend service nodes to be forwarded. It is limited to the service node pool of the listener; the array length can be 0. See ForwardTargetSet for detailed structure. |**Yes**| #### FixedResponseConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **HttpCode** | int | Returned HTTP response codes, only supporting 2xx, 4xx, 5xx numbers, where x is any digit. |**Yes**| | **Content** | string | Returned fixed content. Supports storing up to 1 KB, only supports printable characters within the ASCII code range ch >= 32 && ch < 127, excluding $. |No| #### InsertHeaderConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Key** | string | The inserted header field name must be 1 to 40 characters long and can include uppercase and lowercase letters a-z, numbers, underscores (_), and hyphens (-). The header field name cannot be reused in InsertHeader.

The header field cannot use the following (case insensitive):

x-real-ip, x-forwarded-for, x-forwarded-proto, x-forwarded-srcport, ucloud-alb-trace, connection, upgrade, content-length, transfer-encoding, keep-alive, te, host, cookie, remoteip, authority. |**Yes**| | **Value** | string | Inserted header field content.

When ValueType is SystemDefined, the values are as follows:
ClientSrcPort: Client port.
ClientSrcIp: Client IP address.
Protocol: Protocol of the client's request (HTTP or HTTPS).
RuleID: ID of the forwarding rule hit by the client's request.
ALBID: ALB ID.
ALBPort: ALB port.

When ValueType is UserDefined:

You can customize the header field content, with a length limit of 1\~128 characters, supporting printable characters in the ASCII range ch >= 32 && ch < 127, excluding $.

When ValueType is ReferenceHeader:

You can reference a specific field from the request header, with a length limit of 1\~128 characters, supporting lowercase letters a\~z, numbers, hyphens (-), and underscores (_). |**Yes**| | **ValueType** | string | Header field content type. Values:

UserDefined: User specified.

ReferenceHeader: Referencing a field from the user's request header.

SystemDefined: System defined. |**Yes**| #### CorsConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **AllowOrigin** | array[string] | Allowed access source list. Supports configuring only one element *, or configuring one or more values.

A single value must start with http:// or https://, followed by a correct domain name or a first-level wildcard domain. (Example: http://*.test.abc.example.com)
A single value can be without a port or specify a port, with a port range: 1\~65535.
Supports up to 5 values. |**Yes**| | **AllowHeaders** | array[string] | List of Headers allowed for cross-origin. Supports configuration as * or one or more value entries. A single value entry can only contain uppercase and lowercase letters, numbers, and cannot start or end with an underscore (_) or hyphen (-), with a maximum length limit of 32 characters. Supports up to 20 values. |No| | **ExposeHeaders** | array[string] | List of allowed exposed Headers. Supports configuration as * or one or more value entries. A single value entry can only contain uppercase and lowercase letters, numbers, and cannot start or end with an underscore (_) or hyphen (-), with a maximum length of 32 characters. Supports up to 20 values. |No| | **AllowMethods** | array[string] | Select the allowed HTTP methods for cross-domain access. Values:

GET
POST
PUT
DELETE
HEAD
OPTIONS
PATCH |No| | **AllowCredentials** | string | Allow carrying credential information. Values:

on: Yes.
off: No. |No| | **MaxAge** | int | The maximum cache time for preflight requests in the browser, in seconds.

Value range: -1\~172800. |No| #### RemoveHeaderConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Key** | string | The names of the header fields to be deleted, currently only the following default configured fields can be deleted: X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-SrcPort |**Yes**| #### ForwardTargetSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Id** | string | Identification ID of the service node |**Yes**| | **Weight** | int | Weight. Only valid when the load balancing algorithm of the listener is weighted round robin; Value range [1-100], default value is 1. |No| #### HostConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Values** | array[string] | Value. Currently only supports an array length of 1; The value must meet the conditions of the relevant matching method. |**Yes**| | **MatchMode** | string | Matching method. Limited enumeration values: Regular-Regular, Wildcard-Wildcard domain; Default value: Regular. |No| #### PathConfigSet | Field Name | Type | Description Information | Required | |:---|:---|:---|:---| | **Values** | array[string] | Value. Currently only supports an array length of 1; The value must meet the conditions of the relevant matching method. |**Yes**| ## Example ### Request Example ``` https://api.scloudsg.com/?Action=DescribeListeners &Region=cn-bj2 &ProjectId=org-XXXXX &ListenerId=als-XXXXX &LoadBalancerId=alb-XXXXX &Offset=0 &Limit=10 ``` ### Response Example ```json { "Action": "DescribeListenersResponse", "Listeners": [ { "Certificates": [ { "IsDefault": true, "SSLId": "ssl-XXXXXX" } ], "CompressionEnabled": true, "HTTP2Enabled": false, "HealthCheckConfig": [ { "Enabled": false } ], "IdleTimeout": 60, "ListenPort": 80, "ListenProtocol": "HTTP", "ListenerId": "als-XXXXXX", "Name": "als", "RedirectEnabled": false, "RedirectPort": 7, "Remark": "test_als", "Rules": [ { "IsDefault": true, "Pass": true, "RuleActions": [ { "InsertHeaderConfig": { "Key": "test1", "Value": "ClientSrcPort", "ValueType": "SystemDefined" }, "Order": 1, "Type": "InsertHeader" }, { "InsertHeaderConfig": { "Key": "test2", "Value": "test2", "ValueType": "UserDefined" }, "Order": 2, "Type": "InsertHeader" }, { "InsertHeaderConfig": { "Key": "test3", "Value": "test3", "ValueType": "UserDefined" }, "Order": 3, "Type": "InsertHeader" }, { "Order": 4, "RemoveHeaderConfig": { "Key": "X-Forwarded-Proto" }, "Type": "RemoveHeader" }, { "CorsConfig": { "AllowCredentials": "on", "AllowHeaders": [ "Origin", "Accept", "Accept" ], "AllowMethods": [ "OPTIONS", "HEAD", "GET", "POST", "PUT", "PATCH" ], "AllowOrigin": [ "http://example.com", "http://example.com", "https://example.com:123", "https://example.com:12313" ], "ExposeHeaders": [ "User-Agent", "Cache-Control" ], "MaxAge": -1 }, "Order": 5, "Type": "Cors" }, { "ForwardConfig": { "Targets": [ { "Id": "ars-XXXXX", "Weight": 1 } ] }, "Type": "Forward" } ], "RuleConditions": [ { "PathConfig": { "Values": [ "/" ] }, "Type": "Path" } ], "RuleId": "rule-XXXXXX" }, { "IsDefault": false, "Pass": true, "RuleActions": [ { "ForwardConfig": { "Targets": [ { "Id": "ars-XXXXX", "Weight": 1 } ] }, "Type": "Forward" } ], "RuleConditions": [ { "PathConfig": { "Values": [ "/abc" ] }, "Type": "Path" }, { "HostConfig": { "MatchMode": "Regular", "Values": [ "www.*.com" ] }, "Type": "Host" } ], "RuleId": "rule-XXXXXX" } ], "Scheduler": "Roundrobin", "SecurityPolicyId": "security-tls12s", "StickinessConfig": [ { "CookieName": "test", "Enabled": true, "Type": "UserDefined" } ], "Targets": [ { "Enabled": true, "Id": "ars-XXXXX", "IsBackup": false, "Port": 80, "ResourceIP": "X.X.X.X", "ResourceId": "uhost-XXXXXX", "ResourceName": "UHost1", "ResourceType": "UHost", "State": "Unhealthy", "SubnetId": "subnet-XXXXX", "VPCId": "vnet-XXXXX", "Weight": 1 } ] } ], "RetCode": 0, "TotalCount": 1 } ```