Queries the server groups of an Application Load Balancer (ALB) instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes ListServerGroups

The operation that you want to perform. Set the value to ListServerGroups.

ServerGroupIds Array of String No sgp-atstuj3rtop****

The IDs of the server groups to be queried. You can specify up to 20 IDs at a time.

ServerGroupNames Array of String No Group3

The names of the server groups to be queried. You can specify up to 10 names at a time.

ResourceGroupId String No rg-atstuj3rtop****

The ID of the resource group.

NextToken String No FFmyTO70tTpLG6I3FmYAXG****

The start position of the query. If this parameter is left empty, the query starts from the beginning.

MaxResults Integer No 50

The maximum number of entries to return. This parameter is optional. Valid values: 1 to 100. Default value: 20.

VpcId String No vpc-bp15zckdt37pq72zv****

The ID of the virtual private cloud (VPC).

Tag Array No

The tags that are added to the server group. You can specify up to 10 tags in each request.

Key String No Test

The key of the tag.

Value String No Test

The value of the tag.

Response parameters

Parameter Type Example Description
MaxResults Integer 50

The maximum number of entries returned.

NextToken String caeba0bbb2be03f8****

The end position of the query. If the response does not contain this parameter, all data has been queried.

RequestId String CEF72CEB-54B6-4AE8-B225-F876FF7BA984

The ID of the request.

ServerGroups Array of ServerGroup

The server groups.

HealthCheckConfig Object

The configuration of health checks.

HealthCheckConnectPort Integer 80

The backend port that is used for health checks. Valid values: 0 to 65535.

A value of 0 indicates that the port on a backend server is used for health checks.

HealthCheckEnabled Boolean true

Indicates whether the health check feature is enabled. Valid values:

  • true: enabled
  • false: disabled
HealthCheckHost String www.test.com

The domain name that is used for health checks.

HealthCheckCodes Array of String 200

The HTTP status codes that indicate a successful health check.

HealthCheckHttpVersion String HTTP1.1

The version of the HTTP protocol.

HealthCheckInterval Integer 5

The time interval between two consecutive health checks. Unit: seconds.

HealthCheckMethod String HEAD

The HTTP method that is used for health checks.

HealthCheckPath String /test/index.html

The URL that is used for health checks.

HealthCheckProtocol String HTTP

The protocol that is used for health checks. Valid values: HTTP and TCP.

HealthCheckTimeout Integer 3

The timeout period of a health check. If a backend server does not respond within the specified timeout period, the backend server fails the health check. Unit: seconds.

HealthyThreshold Integer 4

The number of health checks that an unhealthy backend server must consecutively pass before it is declared healthy. In this case, the health status is changed from fail to success.

UnhealthyThreshold Integer 4

The number of health checks that a healthy backend server must consecutively fail before it is declared unhealthy. In this case, the health status is changed from success to fail.

Protocol String HTTP

The server protocol. Valid values:

  • HTTP: allows you to associate HTTPS, HTTP, or QUIC listeners with backend servers.
  • HTTPS: allows you to associate HTTPS listeners with backend servers.
ResourceGroupId String rg-atstuj3rtop****

The ID of the resource group.

Scheduler String Wrr

The scheduling algorithm. Valid values:

  • Wrr: Backend servers that have higher weights receive more requests than those that have lower weights.
  • Wlc: Requests are distributed based on the weight and load of each backend server. The load refers to the number of connections to a backend server. If multiple backend servers have the same weight, requests are routed to the backend server with the least connections.
  • Sch: indicates consistent hashing that is based on source IP addresses.
ServerGroupId String sgp-cige6j****

The ID of the server group.

ServerGroupName String Group3

The name of the server group.

ServerGroupStatus String Available

The status of the server group.

  • Creating: The server group is being created.
  • Available: The server group is available.
  • Configuring: The server group is being configured.
ServerGroupType String Instance

The type of the server group. Valid values:

  • Instance: a server group that consists of servers.
  • Ip: a server group that consists of IP addresses.
StickySessionConfig Object

The configuration of session persistence.

Cookie String B490B5EBF6F3CD402E515D22BCDA****

The cookie that is configured on the backend server.

CookieTimeout Integer 1000

The timeout period of the cookie. Unit: seconds.

StickySessionEnabled Boolean true

Indicates whether session persistence is enabled.

StickySessionType String Insert

The method that is used to handle a cookie. Valid values:

  • Insert: inserts a cookie.

    ALB inserts the server ID as a cookie into the first HTTP or HTTPS response that is sent to a client. The next request from the client will contain this cookie, and the listener will distribute this request to the recorded backend server.

  • Server: rewrites a cookie.

    When ALB detects a user-defined cookie, it uses the user-defined cookie to rewrite the original cookie. The next request from the client will contain the user-defined cookie, and the listener will distribute this request to the recorded backend server.

VpcId String vpc-bp15zckdt37pq72zv****

The ID of the VPC.

Tags Array of Tag

The tags that are added to the server group.

Key String Test

The key of the tag.

Value String Test

The value of the tag.

TotalCount Integer 1000

The total number of entries returned.

Examples

Sample requests

http(s)://[Endpoint]/?Action=ListServerGroups
&ServerGroupIds=["sgp-atstuj3rtop****"]
&ServerGroupNames=["Group3"]
&ResourceGroupId=rg-atstuj3rtop****
&NextToken=FFmyTO70tTpLG6I3FmYAXG****
&MaxResults=50
&VpcId=vpc-bp15zckdt37pq72zv****
&Tag=[{"Key":"Test","Value":"Test"}]
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<ListServerGroupsResponse>
    <MaxResults>50</MaxResults>
    <NextToken>caeba0bbb2be03f8****</NextToken>
    <RequestId>CEF72CEB-54B6-4AE8-B225-F876FF7BA984</RequestId>
    <ServerGroups>
        <HealthCheckConfig>
            <HealthCheckConnectPort>80</HealthCheckConnectPort>
            <HealthCheckEnabled>true</HealthCheckEnabled>
            <HealthCheckHost>www.test.com</HealthCheckHost>
            <HealthCheckCodes>200</HealthCheckCodes>
            <HealthCheckHttpVersion>HTTP1.1</HealthCheckHttpVersion>
            <HealthCheckInterval>5</HealthCheckInterval>
            <HealthCheckMethod>HEAD</HealthCheckMethod>
            <HealthCheckPath>/test/index.html</HealthCheckPath>
            <HealthCheckProtocol>HTTP</HealthCheckProtocol>
            <HealthCheckTimeout>3</HealthCheckTimeout>
            <HealthyThreshold>4</HealthyThreshold>
            <UnhealthyThreshold>4</UnhealthyThreshold>
        </HealthCheckConfig>
        <Protocol>HTTP</Protocol>
        <ResourceGroupId>rg-atstuj3rtop****</ResourceGroupId>
        <Scheduler>Wrr</Scheduler>
        <ServerGroupId>sgp-cige6j****</ServerGroupId>
        <ServerGroupName>Group3</ServerGroupName>
        <ServerGroupStatus>Available</ServerGroupStatus>
        <ServerGroupType>Instance</ServerGroupType>
        <StickySessionConfig>
            <Cookie>B490B5EBF6F3CD402E515D22BCDA****</Cookie>
            <CookieTimeout>1000</CookieTimeout>
            <StickySessionEnabled>true</StickySessionEnabled>
            <StickySessionType>Insert</StickySessionType>
        </StickySessionConfig>
        <VpcId>vpc-bp15zckdt37pq72zv****</VpcId>
        <Tags>
            <Key>Test</Key>
            <Value>Test</Value>
        </Tags>
    </ServerGroups>
    <TotalCount>1000</TotalCount>
</ListServerGroupsResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "MaxResults" : 50,
  "NextToken" : "caeba0bbb2be03f8****",
  "RequestId" : "CEF72CEB-54B6-4AE8-B225-F876FF7BA984",
  "ServerGroups" : [ {
    "HealthCheckConfig" : {
      "HealthCheckConnectPort" : 80,
      "HealthCheckEnabled" : true,
      "HealthCheckHost" : "www.test.com",
      "HealthCheckCodes" : [ "200" ],
      "HealthCheckHttpVersion" : "HTTP1.1",
      "HealthCheckInterval" : 5,
      "HealthCheckMethod" : "HEAD",
      "HealthCheckPath" : "/test/index.html",
      "HealthCheckProtocol" : "HTTP",
      "HealthCheckTimeout" : 3,
      "HealthyThreshold" : 4,
      "UnhealthyThreshold" : 4
    },
    "Protocol" : "HTTP",
    "ResourceGroupId" : "rg-atstuj3rtop****",
    "Scheduler" : "Wrr",
    "ServerGroupId" : "sgp-cige6j****",
    "ServerGroupName" : "Group3",
    "ServerGroupStatus" : "Available",
    "ServerGroupType" : "Instance",
    "StickySessionConfig" : {
      "Cookie" : "B490B5EBF6F3CD402E515D22BCDA****",
      "CookieTimeout" : 1000,
      "StickySessionEnabled" : true,
      "StickySessionType" : "Insert"
    },
    "VpcId" : "vpc-bp15zckdt37pq72zv****",
    "Tags" : [ {
      "Key" : "Test",
      "Value" : "Test"
    } ]
  } ],
  "TotalCount" : 1000
}

Error codes

For a list of error codes, visit the API Error Center.