Querying Backend Server Groups

Function

This API is used to query all backend server groups.

Constraints

This API has the following constraints:

Parameters marker, limit, and page_reverse are used for pagination query.
Parameters marker and page_reverse take effect only when they are used together with parameter limit.

Calling Method

For details, see Calling APIs.

URI

GET /v3/{project_id}/elb/pools

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Specifies the project ID. For details about how to obtain a project ID, see Obtaining a Project ID. Constraints: N/A Range: The value can contain a maximum of 32 characters, including digits and lowercase letters. Default value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
marker	No	String	Definition: Specifies the ID of the last record on the previous page. Constraints: This parameter must be used together with limit. If the parameter is not specified, only resources on the first page are queried. This parameter cannot be left blank or set to an invalid ID. Range: N/A Default value: N/A
limit	No	Integer	Definition: Specifies the number of records returned on each page. Constraints: N/A Range: 0 to 2000 Default value: 2000
page_reverse	No	Boolean	Definition: Specifies whether to use reverse query. Constraints: This parameter must be used together with limit. If page_reverse is set to true and you want to query the resources on the previous page, set the value of marker to the value of previous_marker. Range: true: Query resources on the previous page. false: Query resources on the next page. Default value: false
description	No	Array of strings	Definition: Specifies supplementary information about the backend server group. Multiple descriptions can be used for query in the format of description=xxx&description=xxx. Constraints: N/A Range: N/A Default value: N/A
admin_state_up	No	Boolean	Definition: Specifies the administrative status of the backend server group. Constraints: N/A Range: N/A Default value: N/A
healthmonitor_id	No	Array of strings	Definition: Specifies the ID of the health check configured for the backend server group. Multiple IDs can be used for query in the format of healthmonitor_id=xxx&healthmonitor_id=xxx. Constraints: N/A Range: N/A Default value: N/A
id	No	Array of strings	Definition: Specifies the ID of the backend server group. Multiple IDs can be used for query in the format of id=xxx&id=xxx. Constraints: N/A Range: N/A Default value: N/A
name	No	Array of strings	Definition: Specifies the backend server group name. Multiple names can be used for query in the format of name=xxx&name=xxx. Constraints: N/A Range: N/A Default value: N/A
loadbalancer_id	No	Array of strings	Definition: Specifies the ID of the load balancer with which the backend server group is associated. Multiple IDs can be used for query in the format of loadbalancer_id=xxx&loadbalancer_id=xxx. Constraints: N/A Range: N/A Default value: N/A
protocol	No	Array of strings	Definition: Specifies the protocol used by the backend server group to receive requests from the load balancer. Multiple protocols can be used for query in the format of protocol=xxx&protocol=xxx. Constraints: N/A Range: The value can be TCP, UDP, IP, TLS, HTTP, HTTPS, GRPC, or QUIC. Default value: N/A
lb_algorithm	No	Array of strings	Definition: Specifies the load balancing algorithm used by the load balancer to route requests to backend servers in the associated backend server group. Multiple algorithms can be used for query in the format of lb_algorithm=xxx&lb_algorithm=xxx. Constraints: N/A Range: ROUND_ROBIN: weighted round robin LEAST_CONNECTIONS: weighted least connections SOURCE_IP: source IP hash QUIC_CID: connection ID 2_TUPLE_HASH: 2-tuple hash that is only available for IP backend server groups 3_TUPLE_HASH: 3-tuple hash that is only available for IP backend server groups 5_TUPLE_HASH: 5-tuple hash that is only available for IP backend server groups Default value: N/A
enterprise_project_id	No	Array of strings	Definition: Specifies the ID of the enterprise project. Multiple values can be used for query in the format of: enterprise_project_id=xxx&enterprise_project_id=xxx. Constraints: If enterprise_project_id is not specified, resources in all enterprise projects are queried by default. Fine-grained authorization is performed. The elb:pools:list permission must be assigned to the user group. If enterprise_project_id is specified, the value can be a specific enterprise project ID or all_granted_eps. If the value is a specific enterprise project ID, only resources in the enterprise project are queried. If the value is all_granted_eps, resources in the enterprise projects with the elb:pools:list permission are queried. Range: N/A Default value: N/A
ip_version	No	Array of strings	Definition: Specifies the IP address version supported by the backend server group. Multiple versions can be used for query in the format of ip_version=xxx&ip_version=xxx. Constraints: N/A Range: N/A Default value: N/A
member_address	No	Array of strings	Definition: Specifies the IP address of the backend server. This is a query parameter and will not be included in the response. Multiple IP addresses can be used for query in the format of member_address=xxx&member_address=xxx. Constraints: N/A Range: N/A Default value: N/A
member_device_id	No	Array of strings	Definition: Specifies the ID of the ECS that is associated with the load balancer as a backend server. This is a query parameter and will not be included in the response. Multiple IDs can be used for query in the format of member_device_id=xxx&member_device_id=xxx. Constraints: N/A Range: N/A Default value: N/A
member_deletion_protection_enable	No	Boolean	Definition: Specifies whether to enable deletion protection. Constraints: N/A Range: false (disable this option) or true (enable this option). All resources will be queried if this parameter is not passed. Default value: N/A This parameter is unsupported. Please do not use it.
listener_id	No	Array of strings	Definition: Specifies the IDs of the associated listeners, including the listeners associated through forwarding policies. Multiple IDs can be used for query in the format of listener_id=xxx&listener_id=xxx. Constraints: N/A Range: N/A Default value: N/A
member_instance_id	No	Array of strings	Definition: Specifies the backend server ID. This is a query parameter and will not be included in the response. Multiple IDs can be used for query in the format of member_instance_id=xxx&member_instance_id=xxx. Constraints: N/A Range: N/A Default value: N/A
vpc_id	No	Array of strings	Definition: Specifies the ID of the VPC where the backend server group works. Constraints: N/A Range: N/A Default value: N/A
type	No	Array of strings	Definition: Specifies the type of the backend server group. Constraints: N/A Range: instance: Any type of backend servers can be added. vpc_id is mandatory. ip: Only IP as backend servers can be added. vpc_id cannot be specified. "": Any type of backend servers can be added. Default value: N/A
quic_cid_len	No	Integer	Definition: Specifies the QUIC connection ID that is used to query backend server groups. It is used only as a query condition but not as a response parameter. Multiple values can be used for query in the format of quic_cid_len=3&quic_cid_len=5. Constraints: N/A Range: N/A Default value: N/A
quic_cid_offset	No	Integer	Definition: Specifies the QUIC connection ID offset that is used to query backend server groups. It is used only as a query condition but not as a response parameter. Multiple values can be used for query in the format of quic_cid_offset=1&quic_cid_offset=3. Constraints: N/A Range: N/A Default value: N/A
az_affinity	No	Array of strings	Definition: Specifies whether AZ affinity of a backend server group is enabled. The following is an example: "az_affinity": { "enable": "true" } Multiple values can be used for query in the format of az_affinity=enable=true&az_affinity=enable=false. Constraints: N/A Range: N/A Default value: N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition: Specifies the token used for IAM authentication. Constraints:N/A Range: N/A Default value: N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
request_id	String	Definition: Specifies the request ID. Range: The value is automatically generated, and can contain characters including digits, lowercase letters, and hyphens (-).
page_info	PageInfo object	Definition: Specifies the pagination information.
pools	Array of Pool objects	Definition: Lists the backend server groups.

**Table 5** PageInfo
Parameter	Type	Description
previous_marker	String	Definition: Specifies the ID of the first record in the pagination query result. If page_reverse is set to true, this parameter is used together to query resources on the previous page. Range: N/A
next_marker	String	Definition: Specifies the ID of the last record in the pagination query result. It is usually used to query resources on the next page. Range: N/A
current_count	Integer	Definition: Specifies the number of records returned on the current page. Range: N/A

**Table 6** Pool
Parameter	Type	Description
admin_state_up	Boolean	Definition: Specifies the administrative status of the backend server group. The value can only be true. Range: true (enabled)
az_affinity	AzAffinity object	Definition: Specifies how AZ affinity is configured for the backend server group.
description	String	Definition: Provides supplementary information about the backend server group. Range: N/A
healthmonitor_id	String	Definition: Specifies the ID of the health check configured for the backend server group. Range: N/A
id	String	Definition: Specifies the backend server group ID. Range: N/A
lb_algorithm	String	Definition: Specifies the load balancing algorithm used by the load balancer to route requests to backend servers in the associated backend server group. Range: ROUND_ROBIN: weighted round robin LEAST_CONNECTIONS: weighted least connections SOURCE_IP: source IP hash QUIC_CID: connection ID 2_TUPLE_HASH: 2-tuple hash that is only available for IP backend server groups 3_TUPLE_HASH: 3-tuple hash that is only available for IP backend server groups 5_TUPLE_HASH: 5-tuple hash that is only available for IP backend server groups If this parameter is not specified for an IP backend server group, 5_TUPLE_HASH is used by default. QUIC_CID is not supported.
listeners	Array of ListenerRef objects	Definition: Specifies the IDs of the listeners with which the backend server group is associated.
loadbalancers	Array of LoadBalancerRef objects	Definition: Specifies the IDs of the load balancers with which the backend server group is associated.
members	Array of MemberRef objects	Definition: Specifies the IDs of backend servers in the backend server group.
name	String	Definition: Specifies the backend server group name. Range: N/A
project_id	String	Definition: Specifies the project ID of the backend server group. Range: N/A
protocol	String	Definition: Specifies the protocol used by the backend server group to receive requests from the load balancer. Constraints: N/A Range: The value can be TCP, UDP, IP, TLS, HTTP, HTTPS, GRPC, or QUIC. Default value: N/A QUIC is not supported.
session_persistence	SessionPersistence object	Definition: Specifies the sticky session.
ip_version	String	Definition: Specifies the IP address version supported by the backend server group.
slow_start	SlowStart object	Definition: Specifies slow start details. After you enable slow start, new backend servers added to the backend server group are warmed up, and the number of requests they can receive increases linearly during the configured slow start duration. This parameter is not supported by gateway load balancers. Please do not use it.
member_deletion_protection_enable	Boolean	Definition: Whether to enable removal protection for the backend server. Once the option is enabled, backend servers cannot be removed from the backend server group. Constraints: Once the option is enabled, an error will be returned when the following APIs are called to: Delete a load balancer and its associated resources (DELETE /v3/{project_id}/elb/loadbalancers/{loadbalancer_id}/force-elb). Delete a load balancer and its associated EIPs (POST /v3/{project_id}/elb/loadbalancers/{loadbalancer_id}/delete-cascade). Delete a listener and its associated resources (DELETE /v3/{project_id}/elb/listeners/{listener_id}/force). Delete a backend server group and its associated resources (DELETE /v3/{project_id}/elb/pools/{pool_id}/delete-cascade). Remove a backend server (DELETE /v3/{project_id}/elb/pools/{pool_id}/members/{member_id}). Remove backend servers in batches (POST /v3/{project_id}/elb/pools/{pool_id}/members/batch-delete). Range: false (disable this option) or true (enable this option). Default value: false NOTE: Disable deletion protection or removal protection for your resources before deregistering your account. This parameter is unsupported. Please do not use it.
created_at	String	Definition: Specifies the creation time. Range: The value must be a UTC time in the yyyy-MM-dd'T'HH:mm:ss'Z' format.
updated_at	String	Definition: Specifies the update time. Range: The value must be a UTC time in the yyyy-MM-dd'T'HH:mm:ss'Z' format.
vpc_id	String	Definition: Specifies the ID of the VPC where the backend server group works. Range: N/A
type	String	Definition: Specifies the backend server group type. Range: instance: Any type of backend servers can be added. vpc_id is mandatory. ip: Only IP as backend servers can be added. vpc_id cannot be specified. type cannot be set to ip if the backend server group protocol is IP. "": Any type of backend servers can be added.
any_port_enable	Boolean	Definition: Specifies whether to enable any_port_enable for a backend server group. If this option is enabled, the listener routes the requests to the backend server over the same port as the frontend port. If this option is disabled, the listener routes the requests over the port specified by protocol_port. Constraints: This option is available only for TCP, UDP, or QUIC backend server groups. Range: false (disable this option) or true (enable this option). This parameter is unsupported. Please do not use it.
connection_drain	ConnectionDrain object	Definition: Specifies the configurations of deregistration delay. This parameter takes effect when: A backend server is removed from a backend server group. A backend server is detected unhealthy or health checks fail. The weight of a backend server is 0. This parameter is unsupported. Please do not use it.
enterprise_project_id	String	Definition: Specifies the ID of the enterprise project. Range: 0: The resource belongs to the default enterprise project. A string in UUID format indicates a non-default enterprise project.
pool_health	PoolHealth object	Definition: Specifies the configurations of the pool health feature.
public_border_group	String	Definition: Specifies the public border group. Range: center: public border group of the central site Edge site name: public border group of an edge site This parameter is unsupported. Please do not use it.
quic_cid_hash_strategy	QuicCidHashStrategy object	Definition: Specifies multi-path distribution configuration based on destination connection IDs.

**Table 7** AzAffinity
Parameter	Type	Description
enable	Boolean	Definition: Specifies whether to enable AZ affinity for the backend server group. If this parameter is set to true, ELB forwards traffic across the backend servers in the same AZ as the load balancer. Constraints: This parameter is available only for IP, TCP, and UDP backend server groups. This parameter is not available for backend server groups that are associated with TLS listeners. If the parameter is set to true, parameter pool_health will be ignored. Range: false (disable this option) or true (enable this option). Default value: N/A
az_minimum_healthy_member_percentage	Integer	Definition: Specifies a percentage that is used to determine the health of an AZ. If the percentage of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_percentage shows the percentage of backend servers that are healthy in a backend server group of an AZ. The number of healthy servers is rounded up. For example, in AZ A, if there are three backend servers in the backend server group and az_minimum_healthy_member_percentage is set to 66%, the number of healthy servers is rounded up to 2 (3 × 0.66 = 1.98). If there are fewer than two healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. If az_minimum_healthy_member_percentage is set to 67%, the number of healthy servers is rounded up to 3 (3 × 0.67 = 2.01). If there are fewer than three healthy servers in AZ A, az_unhealthy_fallback_strategy is triggered. Constraints: If enable is set to true, az_minimum_healthy_member_percentage and az_minimum_healthy_member_count cannot be set to -1 at the same time. If enable is set to true, either az_minimum_healthy_member_percentage or az_minimum_healthy_member_count must be set to -1. Range: an integer ranging from -1 to 100. -1 indicates that az_minimum_healthy_member_count takes effect. Default value: N/A
az_minimum_healthy_member_count	Integer	Definition: Specifies a number that is used to determine the health of an AZ. If the number of healthy servers in the AZ of the load balancer falls below the specified value, az_unhealthy_fallback_strategy is triggered. az_minimum_healthy_member_count shows the number of healthy servers in a backend server group of an AZ. Constraints: If enable is set to true, az_minimum_healthy_member_percentage and az_minimum_healthy_member_count cannot be set to -1 at the same time. If enable is set to true, either az_minimum_healthy_member_percentage or az_minimum_healthy_member_count must be set to -1. Range: an integer ranging from -1 to 10000. -1 indicates that az_minimum_healthy_member_percentage takes effect. Default value: N/A
az_unhealthy_fallback_strategy	String	Definition: Specifies how traffic will be distributed across backend servers in an AZ if the percentage or number of healthy servers in the AZ of the load balancer falls below the specified value. Range: forward_to_all_member_of_local_az: forwards requests across all backend servers in the same AZ as the load balancer, even if some servers are unhealthy. forward_to_healthy_member_of_remote_az: forwards requests across healthy backend servers in different AZs from the load balancer. forward_to_all_healthy_member: forwards requests across healthy backend servers in all AZs. forward_to_all_member: forwards requests across all backend servers in all AZs, even if some servers are unhealthy. Constraints: N/A Default value: forward_to_all_member_of_local_az

**Table 8** ListenerRef
Parameter	Type	Description
id	String	Definition: Specifies the listener ID. Range: N/A

**Table 9** LoadBalancerRef
Parameter	Type	Description
id	String	Definition: Specifies the load balancer ID.

**Table 10** MemberRef
Parameter	Type	Description
id	String	Definition: Specifies the backend server ID.

**Table 11** SessionPersistence
Parameter	Type	Description
cookie_name	String	Definition: Specifies the cookie name. Range: The value can contain a maximum of 1,024 characters. This parameter is unsupported. Please do not use it.
type	String	Definition: Specifies the sticky session type. Constraints: If the protocol of the backend server group is TCP or UDP, only SOURCE_IP takes effect. If the protocol of the backend server group is HTTP or HTTPS, only HTTP_COOKIE takes effect. Range: SOURCE_IP, HTTP_COOKIE, or APP_COOKIE.
persistence_timeout	Integer	Definition: Specifies the stickiness duration, in minutes. This parameter will not take effect when type is set to APP_COOKIE. Range: If the protocol of the backend server group is TCP, UDP, or QUIC, the value ranges from 1 to 60, and the default value is 1. If the protocol of the backend server group is HTTP or HTTPS, the value ranges from 1 to 1440, and the default value is 1440.

**Table 12** SlowStart
Parameter	Type	Description
enable	Boolean	Definition: Specifies whether to enable slow start. Range: true: This option will be enabled. false: This option will be disabled.
duration	Integer	Definition: Specifies the slow start duration, in seconds. Range: 30 to 1200, in seconds.

**Table 13** ConnectionDrain
Parameter	Type	Description
enable	Boolean	Definition: Specifies whether to enable connection_drain. Constraints: N/A Range: The value can be true (enable this option) or false (disable this option). Default value: N/A
timeout	Integer	Definition: Specifies the deregistration delay timeout, in seconds. Constraints: N/A Range: 10 to 4000, in seconds. Constraints: N/A

**Table 14** PoolHealth
Parameter	Type	Description
minimum_healthy_member_count	Integer	Definition: Specifies the number of healthy backend servers below which the backend server group is considered as unhealthy. Constraints: N/A Range: 0 (default): pool_health does not take effect. 1: pool_health takes effect. Default value: N/A This parameter is unsupported. Please do not use it.

**Table 15** QuicCidHashStrategy
Parameter	Type	Description
len	Integer	Definition: Specifies the length of the hash factor in the connection ID. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 1 to 20 Default value: 3
offset	Integer	Definition: Specifies the start position in the connection ID as the hash factor. Constraints: This parameter is valid only when the load balancing algorithm is QUIC_CID. Range: 0 to 19 Default value: 1

Example Requests

Querying backend server groups

GET https://{ELB_Endpoint}/v3/99a3fff0d03c428eac3678da6a7d0f24/elb/pools?limit=2

Example Responses

Status code: 200

Successful request.

{
  "pools" : [ {
    "lb_algorithm" : "ROUND_ROBIN",
    "protocol" : "HTTP",
    "type" : "",
    "vpc_id" : "",
    "description" : "",
    "admin_state_up" : true,
    "member_deletion_protection_enable" : false,
    "loadbalancers" : [ {
      "id" : "309a0f61-0b62-45f2-97d1-742f3434338e"
    } ],
    "project_id" : "99a3fff0d03c428eac3678da6a7d0f24",
    "session_persistence" : {
      "cookie_name" : "my_cookie",
      "type" : "APP_COOKIE",
      "persistence_timeout" : 1
    },
    "healthmonitor_id" : "",
    "listeners" : [ ],
    "members" : [ ],
    "id" : "73bd4fe0-ffbb-4b56-aab4-4f26ddf7a103",
    "name" : "",
    "ip_version" : "v4",
    "pool_health" : {
      "minimum_healthy_member_count" : 0
    }
  }, {
    "lb_algorithm" : "SOURCE_IP",
    "protocol" : "TCP",
    "description" : "",
    "admin_state_up" : true,
    "member_deletion_protection_enable" : false,
    "loadbalancers" : [ {
      "id" : "d9763e59-64b7-4e93-aec7-0ff7881ef9bc"
    } ],
    "project_id" : "99a3fff0d03c428eac3678da6a7d0f24",
    "session_persistence" : {
      "cookie_name" : "",
      "type" : "SOURCE_IP",
      "persistence_timeout" : 1
    },
    "healthmonitor_id" : "",
    "listeners" : [ {
      "id" : "8d21db6f-b475-429e-a9cb-90439b0413b2"
    } ],
    "members" : [ ],
    "id" : "74db02d1-5711-4c77-b383-a450e2b93142",
    "name" : "pool_tcp_001",
    "ip_version" : "dualstack",
    "pool_health" : {
      "minimum_healthy_member_count" : 0
    },
    "az_affinity" : {
      "enable" : true,
      "az_minimum_healthy_member_percentage" : -1,
      "az_minimum_healthy_member_count" : 10000,
      "az_unhealthy_fallback_strategy" : "forward_to_all_member_of_local_az"
    }
  } ],
  "page_info" : {
    "next_marker" : "74db02d1-5711-4c77-b383-a450e2b93142",
    "previous_marker" : "73bd4fe0-ffbb-4b56-aab4-4f26ddf7a103",
    "current_count" : 2
  },
  "request_id" : "a1a7e852-1928-48f7-bbc9-ca8469898713"
}