Help Center/ Workspace/ API Reference/ Workspace Application Streaming APIs/ Server Group Management/ Querying Server Groups

Updated on 2026-05-21 GMT+08:00

Querying Server Groups

Function

Queries server groups.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
workspace:serverGroup:list	List	serverGroup *	-	-	-
workspace:serverGroup:list	List	-	g:RequestTag/<tag-key> g:TagKeys g:EnterpriseProjectId	-	-

URI

GET /v1/{project_id}/app-server-groups

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Unique ID of a project

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
offset	No	Integer	Query offset. The default value is 0.
limit	No	Integer	Number of records to be queried. The value ranges from 1 to 100. The default value is 10.
server_group_name	No	String	Server group name.
server_group_id	No	String	Unique ID of a server group.
app_type	No	String	Application group type: SESSION_DESKTOP_APP: session desktop application COMMON_APP: common application
tags	No	String	Queries server groups whose tag field contains this value.
enterprise_project_id	No	String	Enterprise project ID. (If this parameter is left blank or set to 0, the default enterprise project is used.)
is_secondary_server_group	No	String	Whether the server group is a standby one. If this parameter is not specified, all server groups are queried by default. true: standby server group false: primary server group (default value)

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
count	Integer	Total number.
items	Array of ServerGroup objects	Server group list. The maximum number of returned records is the maximum number of records on each page.

**Table 5** ServerGroup
Parameter	Type	Description
id	String	Unique ID of a server group.
name	String	ECS group name.
description	String	Server Group Description.
image_id	String	Specifies the ID of the image associated with the ECS group, which is used to create ECSs in the corresponding group.
os_type	String	System type. Currently, only Windows is supported. Linux - Windows - Other -
product_id	String	Product ID.
subnet_id	String	Specifies the subnet ID of the NIC.
system_disk_type	String	Disk type. For details about how to obtain available disk types, see parameter ListVolumeType. Options: ESSD: Extreme SSD SSD: Ultra-high I/O GPSSD: General-purpose SSD SAS: High I/O SATA: Common I/O
system_disk_size	Integer	Disk capacity in GB.
is_vdi	Boolean	Indicates whether the VDI single-session mode is used.
extra_session_type	String	Paid session type: GPU: GPU session CPU: common CPU session
extra_session_size	Integer	Number of Paid Sessions.
app_type	String	Server Group Application Type SESSION_DESKTOP_APP - Session desktop app COMMON_APP - Common app.
create_time	String	Time when the server group is created.
update_time	String	Server Group Update Time.
storage_mount_policy	String	Mounting policy of the NAS directory on the application streaming server when a user accesses applications on the server. USER: mounts only personal directories SHARE: mounts only shared directories ANY: no restriction on the mounted directory (Both personal and shared NAS directories are automatically mounted.)
enterprise_project_id	String	Enterprise project ID. The value 0 indicates the default enterprise project ID.
primary_server_group_ids	Array of strings	Primary server group IDs.
secondary_server_group_ids	Array of strings	Standby server group IDs.
server_group_status	Boolean	Whether the server is enabled. true indicates yes and false indicates no.
site_type	String	Site type. The options are CENTER and IES.
site_id	String	Site ID.
app_server_flavor_count	Integer	Total Number of Servers.
app_server_count	Integer	Total Number of Servers.
app_group_count	Integer	Total number of associated application groups.
image_name	String	Image Name.
product_info	ProductInfo object	Product specifications.
subnet_name	String	Subnet name.
scaling_policy	ScalingPolicy object	Scaling policy.
tags	Array of TmsTag objects	Tag information.
ou_name	String	Default Organization Name.

**Table 6** ProductInfo
Parameter	Type	Description
product_id	String	Product ID.
flavor_id	String	Specification ID.
type	String	Product type: BASE: basic product package. The package image does not contain other commercial software products except the OS. Only this type of package can be used for private images. ADVANCED: advanced product package. The package image contains some commercial software products.
architecture	String	Product architecture. Currently, only x86 is supported. x86 arm.
cpu	String	CPU.
cpu_desc	String	CPU Description.
memory	String	Memory size, in MB.
is_gpu	Boolean	Specifies whether the flavor is of the GPU type.
system_disk_type	String	System disk type. SSD: ultra-high I/O disk SAS: high I/O disk
system_disk_size	String	System Volume Size.
gpu_desc	String	GPU Description.
descriptions	String	Description.
charge_mode	String	Package ID. 1: Yearly/Monthly. 0: indicates pay-per-use.
contain_data_disk	Boolean	Specifies whether data disks are included in the package charging.
resource_type	String	Resource type. -hws.resource.type.workspace.volume: Workspace desktop disk -hws.resource.type.workspace.desktop: Workspace desktop -hws.resource.type.workspace.appstream: Workspace Application Streaming -hws.resource.type.workspace.appstreamsession: Workspace Application Streaming multi-session
cloud_service_type	String	Cloud service type. hws.service.type.vdi hws.service.type.marketplace
volume_product_type	String	Disk type. workspace
sessions	Integer	Maximum number of sessions supported by a package by default.
status	String	Status of a product package in sales mode. The value comes from cond:operation:status of the ECS. If this parameter is not set, the product is in the normal state. normal: normal commercial use abandon: offline (not displayed) sellout - sold out obt - OBT obt_sellout - OBT sold out promotion: recommended (equivalent to normal, also for commercial use)
cond_operation_az	String	Status of a product package in an AZ. This parameter is used together with status. NOTE: This parameter takes effect AZ-wide. If an AZ is not configured in this parameter, the value of the parameter status is used by default. Otherwise, this parameter is used. Format: az(xx). The value in parentheses is the flavor status of the AZ. If the parentheses are left blank, the configuration is invalid. For example, a package is in commercial use in AZ 0 and AZ 3, sold out in AZ 1, in OBT in AZ 2, and out of service in other AZs. Then, configure parameters as follows: status: abandon "cond_operation_az": az0(normal), az1(sellout), az2(obt), az3(normal) Note: This parameter is mandatory if the flavor status in an AZ is different from the configured status.
sub_product_list	Array of strings	Subproducts of DeHs.
domain_ids	Array of strings	Dedicated domainId of the product.
package_type	String	Package type: general: general package dedicated: dedicated host package
expire_time	String	Expiration time of the product package. The product will be gradually brought offline after the expiration time.
support_gpu_type	String	GPU types supported by the product package. A30 A40 A100 RTX5000

**Table 7** ScalingPolicy
Parameter	Type	Description
enable	Boolean	Indicates whether to enable the policy. The policy is enabled by default. true: yes false: disabled.
max_scaling_amount	Integer	Maximum number of servers whose capacity can be expanded.
single_expansion_count	Integer	Maximum number of servers whose capacity can be expanded at a time.
scaling_policy_by_session	ScalingPolicyBySession object	Session-based scaling policy.
scaling_policy_by_resource	ScalingPolicyByResource object	Resource-based elastic scaling policy.

**Table 8** ScalingPolicyBySession
Parameter	Type	Description
session_usage_threshold	Integer	Total session usage of a group (capacity expansion after the threshold is reached).
shrink_after_session_idle_minutes	Integer	Releases instances that have no session connection within a specified period.

**Table 9** ScalingPolicyByResource
Parameter	Type	Description
cpu_usage_threshold	Integer	Total CPU usage of a group (scale-out is performed when the threshold is reached).
mem_usage_threshold	Integer	Total memory usage of a group (scale-out is performed when the threshold is reached).
gpu_usage_threshold	Integer	Total GPU usage of a group (scale-out is performed when the threshold is reached).

**Table 10** TmsTag
Parameter	Type	Description
key	String	Key. The value can contain a maximum of 128 Unicode characters. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @ The value cannot start or end with a space.
value	String	Value. The value can contain a maximum of 255 Unicode characters. It can contain UTF-8 letters, digits, spaces, and the following characters: _ . : = + - @

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 401

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 403

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 404

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 405

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 500

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Status code: 503

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Example Requests

GET /v1/a4da8115c9d8464ead3a38309130523f/app-server-groups?limit=10&server_group_id=bc05da52-89df-45ba-8146-13fe3ce7c45a&server_group_name=&offset=0

Example Responses

Status code: 200

Response to a successful request.

{
  "count" : 1,
  "items" : [ {
    "id" : "bc05da52-89df-45ba-8146-13fe3ce7c45a",
    "name" : "ApiExpirezSr5_1HgOfh56",
    "description" : "",
    "image_id" : "6579b42e-f345-4452-ae3a-fa0687564943",
    "os_type" : "Windows",
    "product_id" : "workspace.appstream.general.xlarge.2",
    "subnet_id" : "a5842cb4-5718-4b0a-8b27-3a3e9c74f977",
    "system_disk_type" : "SATA",
    "system_disk_size" : 60,
    "is_vdi" : false,
    "app_type" : "COMMON_APP",
    "create_time" : "2023-06-06T14:14:36.416Z",
    "update_time" : "2023-06-06T14:14:38.127Z",
    "app_server_flavor_count" : 0,
    "app_server_count" : 0,
    "app_group_count" : 0,
    "image_name" : "ApiExplore_Image_01",
    "product_info" : {
      "product_id" : "workspace.appstream.general.xlarge.2",
      "flavor_id" : "s2.large.2",
      "type" : "BASE",
      "architecture" : "x86",
      "cpu" : "2",
      "memory" : "4096",
      "is_gpu" : false,
      "system_disk_type" : "SAS",
      "system_disk_size" : "80",
      "descriptions" : "s2.large.2 Cloud Application General-Purpose | 2 vCPUs | 4 GB memory",
      "charge_mode" : "0",
      "contain_data_disk" : false,
      "resource_type" : "hws.resource.type.workspace.appstream",
      "cloud_service_type" : "hws.service.type.vdi",
      "volume_product_type" : "workspace",
      "sessions" : 1,
      "status" : "abandon",
      "cond_operation_az" : "cn-north-7c(abandon),cn-north-7b(abandon),cn-north-7a(normal)",
      "domain_ids" : [ ]
    },
    "subnet_name" : "subnet-config",
    "ou_name" : ""
  } ]
}

Status Codes

Status Code	Description
200	Response to a successful request.
400	The request cannot be understood by the server due to malformed syntax.
401	Authentication failed.
403	Permissions required.
404	No resources found.
405	The request method is not allowed.
500	An internal service error occurred. For details, see the error code description.
503	Service unavailable.

Error Codes

See Error Codes.

Parent topic: Server Group Management

Previous topic: Creating a Server Group

Next topic: Modifying a Server Group

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot