ListServerGroups-阿里云帮助中心

Retrieves a list of server groups.

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:ListServerGroups

get

*ServerGroup

acs:alb:{#regionId}:{#accountId}:servergroup/*

None

Request parameters

Parameter	Type	Required	Description	Example
ServerGroupIds	array	No	The server group IDs. You can specify up to 20 IDs in a single request.
	string	No	The server group ID.	sgp-atstuj3rtop****
ServerGroupNames	array	No	The server group names. You can specify up to 10 names in a single request.
	string	No	The server group name.	Group3
ResourceGroupId	string	No	The resource group ID.	rg-atstuj3rtop****
NextToken	string	No	The token used for the next query. If this is your first query or no next query is to be sent, you can leave this parameter empty. If a subsequent query is to be sent, set this parameter to the value of NextToken from the previous API response.	FFmyTO70tTpLG6I3FmYAXG****
MaxResults	integer	No	The number of entries to return on each page. Valid values: 1 to 100. Default value: 20.	20
VpcId	string	No	The ID of the virtual private cloud (VPC).	vpc-bp15zckdt37pq72zv****
ServerGroupType	string	No	The type of the server group. Valid values: Instance: allows you to add servers of the ECS, ENI, and ECI types. Ip: allows you to add servers with specified IP addresses. Fc: allows you to add Function Compute functions as backend servers. If you do not specify this parameter, the system queries server groups of all types.	Instance
Tag	array<object>	No	The tags. You can specify up to 10 tags in a single request.	Instance
	object	No	A tag that consists of a key-value pair.
Key	string	No	The tag key. The tag key can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and it cannot contain `http://` or `https://`.	Test
Value	string	No	The tag value. The tag value can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and it cannot contain `http://` or `https://`.	Test

Response elements

Element	Type	Description	Example
	object	The data structure that is returned.
MaxResults	integer	The number of entries returned per page.	50
NextToken	string	The token used to retrieve the next page of results. Valid values: If NextToken is empty, no more results are available. If a value is returned, use it to retrieve the next page of results.	caeba0bbb2be03f8****
RequestId	string	The request ID.	CEF72CEB-54B6-4AE8-B225-F876******
ServerGroups	array<object>	The list of server groups.
	array<object>	The list of server groups.
HealthCheckConfig	object	The health check configuration.
HealthCheckConnectPort	integer	The port on the backend server used for health checks. Valid values: 0 to 65535. If the value is 0, the backend server port is used for health checks.	80
HealthCheckEnabled	boolean	Indicates whether health checks are enabled. Valid values: true: Enabled. false: Disabled.	true
HealthCheckHost	string	The domain name that is used for health checks. The private IP address of the backend server (Default): The private IP address of the backend server is used for health checks. A custom domain name: Specify a domain name that meets the following requirements: The domain name must be 1 to 80 characters in length. It can contain lowercase letters, digits, hyphens (-), and periods (.). It must contain at least one period (.). The period (.) cannot be the first or last character. The rightmost domain label can contain only letters and cannot contain digits or hyphens (-). The hyphen (-) cannot be the first or last character. Note This parameter is valid only when `HealthCheckProtocol` is set to `HTTP`, `HTTPS`, or `gRPC`.	www.example.com
HealthCheckCodes	array	The list of status codes that indicate a successful health check.
	string	The status code that indicates a successful health check. If HealthCheckProtocol is set to HTTP or HTTPS, valid values for HealthCheckCodes are http_2xx, http_3xx, http_4xx, and http_5xx. Separate multiple values with commas (,). If HealthCheckProtocol is set to gRPC, the valid status code range for HealthCheckCodes is 0 to 99. You can specify up to 20 value ranges. Separate multiple ranges with commas (,). Note This parameter is valid only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	http_2xx
HealthCheckHttpVersion	string	The HTTP version that is used for health checks. Valid values: HTTP1.0 or HTTP1.1. Note This parameter is valid only when HealthCheckProtocol is set to HTTP or HTTPS.	HTTP1.1
HealthCheckInterval	integer	The interval at which health checks are performed, in seconds. Valid values: 1 to 50.	5
HealthCheckMethod	string	The health check method. Valid values: GET: If the response body exceeds 8 KB, it is truncated. This does not affect the health check result. POST: gRPC health checks use the POST method by default. HEAD: HTTP and HTTPS health checks use the HEAD method by default. Note This parameter is valid only when HealthCheckProtocol is set to HTTP, HTTPS, or gRPC.	HEAD
HealthCheckPath	string	The path that is used for health checks. Note This parameter is valid only when HealthCheckProtocol is set to HTTP or HTTPS.	/test/index.html
HealthCheckProtocol	string	The protocol that is used for health checks. Valid values: HTTP: The load balancer sends HEAD or GET requests to check the health of the backend server. HTTPS: The load balancer sends HEAD or GET requests to check the health of the backend server. HTTPS provides higher security than HTTP because data is encrypted. TCP: The load balancer sends SYN packets to check whether the port of the backend server is reachable. gRPC: The load balancer sends POST or GET requests to check the health of the backend server.	HTTP
HealthCheckTimeout	integer	The timeout for a health check response, in seconds. If a backend server does not respond within this timeout, the health check fails.	3
HealthyThreshold	integer	The number of consecutive successful health checks required for a backend server to change its status from unhealthy to healthy.	4
UnhealthyThreshold	integer	The number of consecutive failed health checks required for a backend server to change its status from healthy to unhealthy.	4
Protocol	string	The backend protocol. Valid values: HTTP: can be associated with HTTPS, HTTP, and QUIC listeners. HTTPS: can be associated with HTTPS listeners. GRPC: can be associated with HTTPS and QUIC listeners.	HTTP
RelatedLoadBalancerIds	array	The IDs of the associated load balancer instances.
	string	The ID of the associated load balancer instance.	alb-n5qw04uq8savfe****
ResourceGroupId	string	The resource group ID.	rg-atstuj3rtop****
Scheduler	string	The scheduling algorithm. Valid values: Wrr: weighted round robin. Backend servers with higher weights receive more requests. Wlc: weighted least connections. The load balancer considers both the weight and the number of active connections for each backend server. If weights are the same, the backend server with the fewest active connections is selected. Sch: consistent hashing. Requests with the same hash key are routed to the same backend server. By default, the hash key is the source IP address. If `UchConfig` is configured, the hash key is a URL parameter.	Wrr
ServerGroupId	string	The server group ID.	sgp-cige6j****
ServerGroupName	string	The server group name.	Group3
ServerGroupStatus	string	The status of the server group. Valid values: Creating: The server group is being created. Available: The server group is available. Configuring: The server group is being updated.	Available
ServerGroupType	string	The type of the server group. Valid values: Instance: an instance-type server group to which you can add ECS instances, elastic network interfaces (ENIs), and ECI instances. IP: an IP-based server group. Function Compute: a Function Compute-based server group.	Instance
StickySessionConfig	object	The sticky session configuration.
Cookie	string	The cookie that is configured on the backend server.	B490B5EBF6F3CD402E515D22BCDA****
CookieTimeout	integer	The timeout period of the cookie, in seconds. Valid values: 1 to 86400. Note This parameter takes effect when StickySessionEnabled is set to true and StickySessionType is set to Insert.	1000
StickySessionEnabled	boolean	Specifies whether to enable sticky sessions. Valid values: true: Enabled. false: Disabled.	false
StickySessionType	string	The method that is used to manage cookies. Valid values: Insert: Inserts a cookie. When a client makes its first request, the load balancer inserts a `SERVERID` cookie into the response. Subsequent requests from the client will include this cookie, and the load balancer will route these requests to the same backend server. Server: Rewrites a cookie. If the load balancer detects a user-defined cookie, it overwrites the original cookie in the response. Subsequent requests from the client will include the new cookie, and the load balancer will route these requests to the same backend server.	Insert
VpcId	string	The ID of the VPC.	vpc-bp15zckdt37pq72zv****
Tags	array<object>	The list of tags that are associated with the server group.
	object	The list of tags that are associated with the server group.
Key	string	The tag key.	Test
Value	string	The tag value.	Test
ConfigManagedEnabled	boolean	Specifies whether to enable configuration management. Valid values: true: Enabled. false: Disabled.	false
UpstreamKeepaliveEnabled	boolean	Specifies whether to enable backend keep-alive connections. Valid values: true: Enabled. false: Disabled.	false
Ipv6Enabled	boolean	Specifies whether IPv6 is enabled. Valid values: true: Enabled. false: Disabled.	false
ServerCount	integer	The number of backend servers in the server group.	1
ServiceName	string	The service name.	test
UchConfig	object	The configuration of URL-based consistent hashing.
Type	string	The type of the parameter. The value must be `QueryString`.	QueryString
Value	string	The value of the consistent hashing parameter.	abc
CreateTime	string	The time when the server group was created.	2022-07-02T02:49:05Z
ConnectionDrainConfig	object	The connection draining configuration. If you enable connection draining, the load balancer allows existing connections to be processed within a specified period of time after a backend server is removed or fails a health check. Note A basic instance does not support connection draining. Only standard instances and WAF-enabled instances support this feature. Connection draining is supported by instance and IP-based server groups, but not by Function Compute-based server groups.
ConnectionDrainEnabled	boolean	Specifies whether to enable connection draining. Valid values: true: Enabled. false: Disabled.	false
ConnectionDrainTimeout	integer	The timeout period for connection draining.	300
SlowStartConfig	object	The slow start configuration. After you enable slow start, the load balancer warms up newly added backend servers for a specified period of time. The number of requests that are routed to these servers increases linearly during the warm-up period. Note A basic instance does not support slow start. Only standard instances and WAF-enabled instances support this feature. Instance and IP-based server groups support slow start. Function Compute-based server groups do not. You can enable slow start only when the scheduling algorithm is weighted round robin.
SlowStartEnabled	boolean	Specifies whether to enable slow start. Valid values: true: Enabled. false: Disabled.	false
SlowStartDuration	integer	The slow start duration, in seconds.	30
CrossZoneEnabled	boolean	Specifies whether to enable cross-zone load balancing for the server group. Valid values: true: Enabled. (Default) false: Disabled.	true
IpVersionAffinityMode	string		Affinity
TotalCount	integer	The total number of entries.	1000

Examples

Success response

JSON format

{
  "MaxResults": 50,
  "NextToken": "caeba0bbb2be03f8****",
  "RequestId": "CEF72CEB-54B6-4AE8-B225-F876******",
  "ServerGroups": [
    {
      "HealthCheckConfig": {
        "HealthCheckConnectPort": 80,
        "HealthCheckEnabled": true,
        "HealthCheckHost": "www.example.com",
        "HealthCheckCodes": [
          "http_2xx"
        ],
        "HealthCheckHttpVersion": "HTTP1.1",
        "HealthCheckInterval": 5,
        "HealthCheckMethod": "HEAD",
        "HealthCheckPath": "/test/index.html",
        "HealthCheckProtocol": "HTTP",
        "HealthCheckTimeout": 3,
        "HealthyThreshold": 4,
        "UnhealthyThreshold": 4
      },
      "Protocol": "HTTP",
      "RelatedLoadBalancerIds": [
        "alb-n5qw04uq8savfe****"
      ],
      "ResourceGroupId": "rg-atstuj3rtop****",
      "Scheduler": "Wrr",
      "ServerGroupId": "sgp-cige6j****",
      "ServerGroupName": "Group3",
      "ServerGroupStatus": "Available",
      "ServerGroupType": "Instance",
      "StickySessionConfig": {
        "Cookie": "B490B5EBF6F3CD402E515D22BCDA****",
        "CookieTimeout": 1000,
        "StickySessionEnabled": false,
        "StickySessionType": "Insert"
      },
      "VpcId": "vpc-bp15zckdt37pq72zv****",
      "Tags": [
        {
          "Key": "Test",
          "Value": "Test"
        }
      ],
      "ConfigManagedEnabled": false,
      "UpstreamKeepaliveEnabled": false,
      "Ipv6Enabled": false,
      "ServerCount": 1,
      "ServiceName": "test",
      "UchConfig": {
        "Type": "QueryString",
        "Value": "abc"
      },
      "CreateTime": "2022-07-02T02:49:05Z",
      "ConnectionDrainConfig": {
        "ConnectionDrainEnabled": false,
        "ConnectionDrainTimeout": 300
      },
      "SlowStartConfig": {
        "SlowStartEnabled": false,
        "SlowStartDuration": 30
      },
      "CrossZoneEnabled": true,
      "IpVersionAffinityMode": "Affinity"
    }
  ],
  "TotalCount": 1000
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.