This interface is used to query desktop information in a desktop pool
Function
This interface is used to query desktop information in a desktop pool.
Debugging
You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.
URI
GET /v2/{project_id}/desktop-pools/{pool_id}/desktops
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
project_id |
Yes |
String |
Project ID. |
pool_id |
Yes |
String |
Specifies the desktop pool ID. |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
inconsistent_type |
No |
String |
This type is used to filter desktops whose specifications are different from those of the desktop pool.
|
offset |
No |
Integer |
Where the pagination query starts. The value starts from 0. |
limit |
No |
Integer |
Limits the quantity of returned desktops in pagination query. The value ranges from 0 to 100. The default value is 10. |
Request 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
Parameter |
Type |
Description |
---|---|---|
pool_desktops |
Array of PoolDesktopsDetailInfo objects |
Pooled desktop details. |
total_count |
Integer |
Total number of desktops. |
on_demand_desktops_num |
Integer |
Total number of pay-per-use desktops. |
period_desktops_num |
Integer |
Total number of yearly/monthly desktops. |
Parameter |
Type |
Description |
---|---|---|
desktop_id |
String |
Desktop ID. |
computer_name |
String |
Desktop name. |
os_host_name |
String |
Computer name in the OS. |
addresses |
Map<String,Array<AddressInfo>> |
Desktop IP addresses. |
ip_addresses |
Array of strings |
IP addresses. |
ipv4 |
String |
IPv4 address of the computer in the OS. |
ipv6 |
String |
IPv6 address of the computer in the OS. |
user_list |
Array of strings |
User list. |
user_group_list |
Array of strings |
User group list. |
desktop_type |
String |
Desktop type.
|
resource_type |
String |
resource_type field, which indicates dedicated desktop (DEDICATED_DESKTOP), pooled desktop (POOLED_DESKTOP), rendering desktop (RENDER_DESKTOP), exclusive host (EXCLUSIVE_HOST), or shared desktop (SHARED_DESKTOP). |
metadata |
Map<String,String> |
Desktop metadata.
|
flavor |
FlavorInfo object |
Product information. |
status |
String |
Desktop status. |
task_status |
String |
Task status.
|
in_maintenance_mode |
Boolean |
Whether the desktop is in maintenance mode. The options are true (yes) and false (no). |
created |
String |
Time when a desktop is created. |
security_groups |
Array of SecurityGroupInfo objects |
Desktop security group. |
login_status |
String |
Login status of a desktop.
|
user_name |
String |
User to whom the desktop belongs. |
attach_user_infos |
Array of AttachInstancesUserInfo objects |
List of users to whom desktops have been assigned. |
product_id |
String |
Product ID. |
share_resource_sku |
String |
Desktop collaboration resource SKU code. |
root_volume |
VolumeDetail object |
System disk. |
data_volumes |
Array of VolumeDetail objects |
Data disks. |
user_group |
String |
User group to which the desktop user belongs.
|
availability_zone |
String |
AZ. |
site_type |
String |
Site type. |
site_name |
String |
Site name. |
product |
ProductInfo object |
Product information. |
ou_name |
String |
Name of the OU to which the desktop is added during desktop creation. |
os_version |
String |
OS version. |
sid |
String |
SID. |
order_id |
String |
Order ID of a yearly/monthly product. |
tags |
Array of Tag objects |
Desktop tags. |
is_support_internet |
Boolean |
Whether to enable the Internet access. The options are true (yes) and false (no). |
internet_mode |
String |
Network access mode.
|
internet_mode_list |
Array of strings |
Network access modes of desktops. |
is_attaching_eip |
Boolean |
Specifies whether an EIP is being bound to the desktop. |
attach_state |
String |
Allocation status.
|
enterprise_project_id |
String |
Enterprise project ID. |
subnet_id |
String |
Subnet ID of the desktop. |
bill_resource_id |
String |
Billing resource ID of the desktop. |
process |
Integer |
Desktop task progress. The value ranges from 0 to 100, or is null. null indicates that there is no task on the desktop. The value from 0 to 100 indicates the task progress percentage. |
root_resource_id |
String |
Root resource ID of the desktop instance. |
hour_package_info |
HourPackageInfo object |
Hourly-billed desktop package details. |
inconsistent_types |
Array of strings |
Different specification type between the desktop and the desktop pool:
|
Parameter |
Type |
Description |
---|---|---|
addr |
String |
IP address. |
version |
String |
IP address type. The value can be 4 (IPv4) or 6 (IPv6). |
OS-EXT-IPS-MAC:mac_addr |
String |
MAC address. |
OS-EXT-IPS:type |
String |
IP address assignment method. -fixed: a private IP address -floating: a floating IP address |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Flavor ID of the desktop. |
links |
Array of FlavorLinkInfo objects |
Shortcut link marker information of the corresponding desktop flavor. |
Parameter |
Type |
Description |
---|---|---|
rel |
String |
Shortcut link marker name. |
hrel |
String |
Corresponding shortcut link. |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Security group ID. |
name |
String |
Security group name. |
Parameter |
Type |
Description |
---|---|---|
user_id |
String |
If type is set to USER, enter the user ID. If type is set to GROUP, enter the user group ID. The backend service checks whether the group ID exists. |
user_name |
String |
Name of the object assigned with a desktop. If type is set to USER, enter the username. If type is set to GROUP, enter the user group name.
|
user_group |
String |
Specifies the user group to which the desktop user belongs.
|
type |
String |
Object type. Options:
|
Parameter |
Type |
Description |
---|---|---|
type |
String |
Desktop data disk type, which must be the same as the disk type provided by the system.
|
size |
Integer |
Disk capacity in GB. |
device |
String |
Directory to which the disk is mounted. |
id |
String |
Unique ID of the disk. |
volume_id |
String |
Disk ID. |
bill_resource_id |
String |
Billing resource ID of the disk. |
create_time |
String |
Time when the disk was created. |
display_name |
String |
Disk name. |
resource_spec_code |
String |
Specifications. |
Parameter |
Type |
Description |
---|---|---|
product_id |
String |
Product ID. |
flavor_id |
String |
Specifications ID. |
type |
String |
Product type.
|
cpu |
String |
CPU. |
memory |
String |
Memory. |
descriptions |
String |
Product description. |
charge_mode |
String |
Billing type of the package. 1 indicates yearly/monthly billing, and 0 indicates pay-per-use billing. |
architecture |
String |
Product architecture. |
is_gpu |
Boolean |
Whether the specifications are of the GPU type. |
package_type |
String |
Package type.
|
system_disk_type |
String |
System disk type. |
system_disk_size |
String |
System disk size. |
contain_data_disk |
Boolean |
Whether data disks are included in the package billing. off indicates no. |
resource_type |
String |
Resource type. |
cloud_service_type |
String |
Cloud service type. |
volume_product_type |
String |
Disk type. |
status |
String |
The status can be normal (by default, on sale), sellout (sold out), and abandon (unavailable). |
Parameter |
Type |
Description |
---|---|---|
key |
String |
Specifies the tag key. This parameter cannot be left blank and can contain a maximum of 128 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,|/. |
value |
String |
Value of a tag, which can contain a maximum of 43 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,|/. |
Parameter |
Type |
Description |
---|---|---|
root_order_id |
String |
Root order ID of the hourly-billed package. |
package_resource_id |
String |
Resource ID of the hourly-billed package. |
package_instance_id |
String |
Instance ID of the hourly-billed package. |
package_spec_code |
String |
specCode of the hourly-billed package. |
combined_product_type_code |
String |
resourceTypeCode of the offering portfolio. |
use_up_policy |
String |
Hourly-billed package exhaustion policy. SHUTDOWN_OR_HIBERNATE: automatic shutdown or hibernation; PAY_PER_USE: pay-per-use billing |
package_duration |
Integer |
Total duration of the hourly-billed package. |
use_duration |
Integer |
Used duration of the hourly-billed package. |
Status code: 400
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Status code: 401
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Status code: 403
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Status code: 404
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Status code: 409
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Status code: 500
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code, which is returned upon failure. |
error_msg |
String |
Error description. |
error_detail |
String |
Error details. |
encoded_authorization_message |
String |
Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason. |
Example Requests
/v2/bcae3e673fd04716a3b9dacdf58ca336/desktop-pools/a130ab3a-72bf-4b71-baa9-af4987c8e338/desktops
Example Responses
Status code: 200
Response to the request for querying users and user groups authorized by the desktop pool.
{ "pool_desktops" : [ { "desktop_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9", "computer_name" : "desktop-mwaxmga", "os_host_name" : "desktop-mwaxmga", "addresses" : { "3596ca3f-0ea0-48ff-8010-3c87e72d9726" : [ { "osextipsmacmacAddr" : "fa:16:3e:36:31:9a", "osextipstype" : "fixed", "addr" : "172.16.11.116", "version" : "4", "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:36:31:9a", "OS-EXT-IPS:type" : "fixed" } ], "016842ec-3d5e-41bd-8ef6-6b34acbec67e" : [ { "osextipsmacmacAddr" : "fa:16:3e:98:4a:0c", "osextipstype" : "fixed", "addr" : "172.26.204.142", "version" : "4", "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:98:4a:0c", "OS-EXT-IPS:type" : "fixed" } ] }, "ip_addresses" : [ "172.16.11.116", "172.26.204.142" ], "ipv4" : "172.16.11.116", "ipv6" : "", "user_list" : [ ], "user_group_list" : [ ], "desktop_type" : "POOLED", "metadata" : { "image_name" : "WKS_WIN1064_UserImage", "metering.resourcespeccode" : "c7.large.2.win", "charging_mode" : "0", "metering.image_id" : "cc3bbc0b-9441-461b-b80b-48c52f3aed08", "metering.resourcetype" : "1", "os_type" : "Windows", "os_bit" : "64", "bill_resource_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9.workspace", "desktop_os_version" : "Version2009(OS Build 19041.1288)" }, "flavor" : { "id" : "c7.large.2", "links" : [ ] }, "status" : "ACTIVE", "task_status" : "", "in_maintenance_mode" : false, "created" : "2025-05-22T09:48:55.864Z", "login_status" : "REGISTERED", "product_id" : "workspace.x86.ultimate.large2", "root_volume" : { "type" : "SAS", "size" : 80, "device" : "/dev/sda", "id" : "f4fc32db36f111f0ade6fa163e5a5e29", "volume_id" : "c6367195-1231-49e4-bb89-c2201d4c1986", "bill_resource_id" : "c6367195-1231-49e4-bb89-c2201d4c1986", "create_time" : "2025-05-22T09:48:47.366Z", "display_name" : "desktop-mwaxmga-volume-0000", "resource_spec_code" : "workspace.volume.high" }, "data_volumes" : [ { "type" : "SAS", "size" : 10, "device" : "/dev/sdb", "id" : "f4fe25e536f111f0ade6fa163e5a5e29", "volume_id" : "14289779-6668-402a-9cfb-2218a4b95507", "bill_resource_id" : "14289779-6668-402a-9cfb-2218a4b95507", "create_time" : "2025-05-22T09:48:47.378Z", "display_name" : "desktop-mwaxmga-volume-0001", "resource_spec_code" : "workspace.volume.high" } ], "availability_zone" : "cn-north-7c", "site_type" : "CENTER", "site_name" : "Huawei Cloud Central Site", "product" : { "product_id" : "workspace.x86.ultimate.large2", "flavor_id" : "c7.large.2", "type" : "BASE", "cpu" : "2", "memory" : "4096", "descriptions" : "Ultimate | 2 vCPUs | 4 GB memory", "charge_mode" : "1", "architecture" : "x86", "is_gpu" : false, "package_type" : "ultimate", "system_disk_type" : "SAS", "system_disk_size" : "140", "contain_data_disk" : false, "resource_type" : "hws.resource.type.workspace.desktop", "cloud_service_type" : "hws.service.type.vdi", "volume_product_type" : "workspace", "status" : "normal" }, "os_version" : "Version2009(OS Build 19041.1288)", "sid" : "4f65a743-283c-4612-bce4-7d4c9a9c3bfe", "tags" : [ ], "is_support_internet" : true, "internet_mode_list" : [ "WORKSPACE_BANDWIDTH" ], "is_attaching_eip" : false, "attach_state" : "UNATTACH", "enterprise_project_id" : "0", "subnet_id" : "c7f30df4-f3ac-4807-9599-18950b05455f", "bill_resource_id" : "ffb9a973-da80-4f58-9f71-5c83c229b3f9", "inconsistent_types" : [ ] } ], "total_count" : 1, "on_demand_desktops_num" : 1, "period_desktops_num" : 0 }
Status Codes
Status Code |
Description |
---|---|
200 |
Response to the request for querying users and user groups authorized by the desktop pool. |
400 |
The request cannot be understood by the server due to malformed syntax. |
401 |
Authentication failed. |
403 |
No operation permissions. |
404 |
No resources found. |
409 |
Operation conflict. |
500 |
An internal service error occurred. For details about the error code, see the error code description. |
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot