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	Yes
Signature	string	User signature generated based on public key and API command, see Signature Algorithm	Yes

Request Parameters

Parameter Name	Type	Description Information	Required
Region	string	Region. See List of Regions and Availability Zones	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.	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]	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]	(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	Configuration related to session persistence. For detailed structure, see StickinessConfigSet.	No
HealthCheckConfig	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]	Information of the added service node. See Target for specific structure.	No
Rules	array[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

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]	Forwarding rule matching conditions. See RuleCondition for specific structure.	No
RuleActions	array[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	Domain-related configuration. Required when Type is Host. See HostConfigSet for specific structure.	No
PathConfig	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	Forward service node related configuration, corresponding to type value: “Forward”. For specific structure, see ForwardConfigSet.	No
FixedResponseConfig	FixedResponseConfigSet	Static return related configuration, corresponding to type value: “FixedResponse”. For specific structure, see FixedResponseConfigSet	No
InsertHeaderConfig	InsertHeaderConfigSet	Insert header-related configuration, corresponding to the type value: “InsertHeader”. For the specific structure, see InsertHeaderConfigSet.	No
CorsConfig	CorsConfigSet	Configuration related to cross-domain, corresponding to type value: “Cors”. For specific structure, see CorsConfigSet.	No
RemoveHeaderConfig	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]	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.sigcalcloud.com/?Action=DescribeListeners
&Region=cn-bj2
&ProjectId=org-XXXXX
&ListenerId=als-XXXXX
&LoadBalancerId=alb-XXXXX
&Offset=0
&Limit=10

Response Example


{
  "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
}