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

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

Querying Specified Server Groups

Function

Queries specified 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:get	Read	serverGroup *	g:ResourceTag/<tag-key> g:EnterpriseProjectId	-	-

URI

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

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

Request Parameters

**Table 2** 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 3** Response body parameters
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.
flavors	Array of Flavor objects	Server specifications.
project_name	String	Project Name.
image_min_disk	Integer	Specifies the minimum memory (MB) required for running the image. The default value is 0.
route_policy	RoutePolicy object	Routing policy of the server group.
image_product_id	String	Specifies the product ID of the image.
image_type	String	Image type. gold: KooGallery images private: private images
ip_virtual	IpVirtual object	Virtual IP function options.

**Table 4** 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 5** 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 6** 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 7** 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 8** 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: _ . : = + - @

**Table 9** Flavor
Parameter	Type	Description
id	String	Specifies the flavor ID of the server.
links	Array of FlavorLink objects	Specifies the shortcut link of the server flavor.

**Table 10** FlavorLink
Parameter	Type	Description
rel	String	Shortcut link marker name.
hrel	String	Specifies the corresponding shortcut link.

**Table 11** RoutePolicy
Parameter	Type	Description
max_session	Integer	Maximum number of sessions on a single server.
cpu_threshold	Integer	CPU usage threshold, in percentage.
gpu_threshold	Integer	GPU usage threshold, in percentage.
mem_threshold	Integer	Memory usage threshold, in percentage.

**Table 12** IpVirtual
Parameter	Type	Description
enable	Boolean	Specifies whether to enable the virtual IP address function. If the virtual IP address function is enabled, extra IP addresses are occupied. Therefore, plan the number of network IP addresses properly. Constraints: Only Windows images are supported. The function switch can be set only when a server group is created. The function switch cannot be updated. Only networks that support dynamic IP address allocation using DHCP are supported.

Status code: 400

**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: 401

**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: 403

**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: 404

**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: 405

**Table 17** 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 18** 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 19** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error message.

Example Requests

None

Example Responses

Status code: 200

Response to a successful request.

{
  "id" : "1",
  "name" : "Server group for process development application",
  "description" : "Software Development Application Server Team of XXX Company",
  "image_id" : "a6ea73e0-9f4b-11ec-b909-0242ac120002",
  "os_type" : "windows",
  "product_id" : "workspace.x86.general.xlarge2",
  "subnet_id" : "0ddf778f-c0fe-4717-9251-001caee7c95e",
  "system_disk_type" : "SSD",
  "system_disk_size" : 10,
  "is_vdi" : false,
  "extra_session_type" : "CPU",
  "extra_session_size" : 1,
  "app_type" : "SESSION_DESKTOP_APP",
  "create_time" : "2022-03-07T10:40:43.858Z",
  "update_time" : "2022-03-07T10:40:43.858Z",
  "storage_mount_policy" : "ANY",
  "enterprise_project_id" : "0",
  "primary_server_group_ids" : [ "string" ],
  "secondary_server_group_ids" : [ "string" ],
  "server_group_status" : false,
  "site_type" : "CENTER",
  "site_id" : "ae985216-83fa-46b6-ab03-a36dcb3dd05a",
  "app_server_flavor_count" : "1",
  "app_server_count" : "1",
  "app_group_count" : "1",
  "image_name" : "Huawei cloud EulerOs 1.0 64bit",
  "product_info" : {
    "product_id" : "workspace.appstream.general.2xlarge.4",
    "flavor_id" : "c3.large.4",
    "type" : "BASE",
    "architecture" : "x86",
    "cpu" : 2,
    "cpu_desc" : "Application Streaming General-Purpose | 4 vCPUs | 8 GB memory",
    "memory" : 4096,
    "is_gpu" : false,
    "system_disk_type" : "SAS",
    "system_disk_size" : 80,
    "gpu_desc" : "GPU graphics acceleration",
    "descriptions" : "GPU graphics-accelerated DG4 | 32-core 128 GB memory 32 GB GPU memory | P02",
    "charge_mode" : 1,
    "contain_data_disk" : false,
    "resource_type" : "hws.resource.type.xxxx.vm",
    "cloud_service_type" : "hws.service.type.xxxxx",
    "volume_product_type" : "workspace",
    "sessions" : 2,
    "status" : "string",
    "cond_operation_az" : "cn-north-5a(normal),cn-north-5b(abandon),cn-north-5c(sellout)",
    "sub_product_list" : [ "xxx", "xxxx" ],
    "domain_ids" : [ "xxx", "xxxx" ],
    "package_type" : "general",
    "expire_time" : "2022-03-07T10:40:43Z",
    "support_gpu_type" : "A40"
  },
  "subnet_name" : "string",
  "scaling_policy" : {
    "enable" : true,
    "max_scaling_amount" : 10,
    "single_expansion_count" : 1,
    "scaling_policy_by_session" : {
      "session_usage_threshold" : 85,
      "shrink_after_session_idle_minutes" : 60
    },
    "scaling_policy_by_resource" : {
      "cpu_usage_threshold" : null,
      "mem_usage_threshold" : 60,
      "gpu_usage_threshold" : 55
    }
  },
  "tags" : [ {
    "key" : "demo01",
    "value" : "01"
  } ],
  "ou_name" : "wksappusers",
  "flavors" : [ {
    "id" : "asdfjkl-2131f-xxx-123123",
    "links" : [ {
      "rel" : "",
      "hrel" : ""
    } ]
  } ],
  "project_name" : "default",
  "image_min_disk" : "10",
  "route_policy" : {
    "max_session" : 2,
    "cpu_threshold" : 85,
    "mem_threshold" : 85
  },
  "image_product_id" : "string",
  "image_type" : "string",
  "ip_virtual" : {
    "enable" : false
  }
}

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: Querying Basic Information About a Tenant Server Group

Next topic: Querying Specified Tenant Server Groups

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