Queries desktops

Function

Queries desktop VMs.

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:desktops:list	List	desktop *	-	-	-
workspace:desktops:list	List	-	g:RequestTag/<tag-key> g:TagKeys g:EnterpriseProjectId	-	-

URI

GET /v2/{project_id}/desktops

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
user_name	No	Array of strings	Desktop owner (fuzzy user name search supported).
computer_name	No	String	Desktop name.
desktop_ip	No	String	Desktop IP address.
offset	No	Integer	Start position for pagination query. The value starts from 0.
limit	No	Integer	Pagination query. The value ranges from 0 to 1000 and defaults to 1000.
pool_id	No	String	Desktop pool ID. Use commas (,) to separate multiple desktop pool IDs.
enterprise_project_id	No	String	Enterprise project ID.
desktop_type	No	String	Desktop type. If this parameter is left empty, all desktops are queried. Use commas (,) to separate multiple types. DEDICATED: common desktop, including dedicated desktop and dedicated desktop. SHARED: Multiple users share the desktop.
is_share_desktop	No	Boolean	Whether the desktop is a collaborative desktop.
subnet_id	No	String	Subnet ID of the desktop.
status	No	String	Desktop running status.
desktop_id	No	Array of strings	Desktop ID. Up to 100 desktop IDs can be queried.
tag	No	String	Desktop tag. Examples: key1=value1 key1=value1, key2=value2

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
total_count	Integer	Total number of desktops.
desktops	Array of SimpleDesktopInfo objects	Desktop information.

**Table 4** SimpleDesktopInfo
Parameter	Type	Description
domain_id	String	Domain ID.
project_id	String	Project ID.
desktop_id	String	Desktop ID.
computer_name	String	Computer name.
os_host_name	String	Computer name in the OS.
created	String	Creation time.
ip_address	String	Desktop IP address.
user_name	String	Username.
attach_user_infos	Array of AttachInstancesUserInfo objects	List of users to whom desktops have been assigned.
user_group	String	Permission group.
sid	String	SID of the desktop.
ou_name	String	OU name.
enterprise_project_id	String	Enterprise project ID.
tags	Array of Tag objects	Tag list.
in_maintenance_mode	Boolean	In administrator maintenance mode or not.
share_resource_sku	String	Desktop collaboration resource SKU code.
desktop_type	String	Desktop type.
desktop_detail_type	String	Details of the desktop type.
subnet_id	String	Subnet ID of the desktop.
bill_resource_id	String	Billing resource ID of the desktop.
status	String	Desktop running status.
task_status	String	Task status of the desktop.
availability_zone	String	AZ.
connect_status	String	Desktop connection status.
pool_id	String	Desktop pool ID.

**Table 5** AttachInstancesUserInfo
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. If type is set to USER, the value is the username of the desktop user. After the desktop is assigned, the user can log in to the desktop. Only letters, digits, hyphens (-), and underscores (_) are allowed. When the domain type is LITE_AD, the value contains 1 to 20 characters starting with a letter. When the domain type is LOCAL_AD, the value contains 1 to 64 characters starting with a letter or digit. A Windows desktop username can contain a maximum of 20 characters, and a Linux desktop username can contain a maximum of 64 characters. The backend service checks whether the username exists. The username cannot be the same as the desktop name. If type is set to GROUP, the value can contain only letters, digits, hyphens (-), and underscores (_).
domain	String	Domain to which the user belongs.
user_group	String	Specifies the user group to which the desktop user belongs. sudo: Linux administrator group. default: default Linux user group. administrators: Windows administrator group. Administrators have full access to the desktop and can make any required changes except for forbidden operations. users: standard Windows user group. Standard users can use most software programs and change system settings that do not affect other users.
type	String	Object type. The default value is USER. The options are: USER: user GROUP: user group

**Table 6** Tag
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: =*<>,\|/.

Status code: 400

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

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

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

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

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

Example Responses

Status code: 200

Response to the request for querying cloud desktops.

{
  "total_count" : 2,
  "desktops" : [ {
    "desktop_id" : "a6f6e2d1-cc62-46f3-865b-9ae6ae0afde0",
    "computer_name" : "ZRYUAN107",
    "created" : "2022-02-23 04:02:07",
    "ip_address" : "10.0.9.25",
    "user_name" : "zryuan1",
    "user_group" : "administrators",
    "sid" : "3db90102-d11d-4d13-9a96-104696d3c6a3",
    "in_maintenance_mode" : false,
    "share_resource_sku" : "workspace.collaborativedesktop.6party.standard"
  }, {
    "desktop_id" : "248077ea-bb64-4e58-b5e8-6b686600920e",
    "computer_name" : "CHENYC01",
    "created" : "2022-02-22 12:14:59",
    "ip_address" : "10.0.9.103",
    "user_name" : "chenyc",
    "user_group" : "administrators",
    "sid" : "352cf09d-ee15-4ef1-aa49-8d673972b4e6",
    "in_maintenance_mode" : true,
    "share_resource_sku" : "workspace.collaborativedesktop.6party.standard"
  } ]
}

Status Codes

Status Code	Description
200	Response to the request for querying cloud desktops.
400	The request cannot be understood by the server due to malformed syntax.
401	Authentication failed.
403	No operation permissions.
404	No resources found.
500	An internal service error occurred. For details about the error code, see the error code description.