Help Center/ Workspace/ API Reference/ Workspace APIs/ Desktop/ Queries the desktop details list.

Updated on 2024-01-10 GMT+08:00

View PDF

Queries the desktop details list.

Function

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}/desktops/detail

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

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
status	No	String	Desktop status. ACTIVE: The desktop is running. SHUTOFF: The desktop is shut down. ERROR: The desktop is abnormal.
user_name	No	String	Specifies the user to which the desktop belongs. This parameter is invalid when user_names is transferred.
user_names	No	Array	Specifies the user to which the desktop belongs. A maximum of 100 users can be filtered in batches.
sort_field	No	String	Sorting field name, which must be used together with the sort_type field. created: indicates the creation time. computer_name: indicates the desktop name.
sort_type	No	String	Sorting type. The default value is ascending. This parameter must be used together with sort_field. ASC: ascending order. DESC: descending order.
computer_name	No	String	Computer 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 500 and defaults to 500.
desktop_id	No	Array	Desktop ID.
desktop_type	No	String	Desktop type. If this parameter is left empty, all desktops are queried. DEDICATED: common desktops, including exclusive desktops and dedicated desktops. POOLED: pooled desktop, that is, desktop in a desktop pool.
tag	No	String	Desktop tag. Examples are as follows: key1=value1 key1=value1,key2=value2
pool_id	No	String	Desktop pool ID. Use commas (,) to separate multiple desktop pool IDs.
user_attached	No	Boolean	Whether a desktop is assigned to a user.
enterprise_project_id	No	String	Enterprise project ID.
image_id	No	String	Image ID.
charge_mode	No	String	Billing mode. The value can be 0 (monthly) or 1 (pay-per-use).
in_maintenance_mode	No	Boolean	Filter by maintenance mode.

Request Parameters

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

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
desktops	Array of DesktopDetailInfo objects	Desktop details list.
total_count	Integer	Total number of desktops.

**Table 5** DesktopDetailInfo
Parameter	Type	Description
desktop_id	String	Desktop ID.
computer_name	String	Desktop name.
addresses	Map<String,Array<AddressInfo>>	Desktop IP addresses.
ip_addresses	Array of strings	IP addresses.
user_list	Array of strings	User list.
user_group_list	Array of strings	User group list.
desktop_type	String	Desktop type. DEDICATED: a dedicated desktop
metadata	Map<String,String>	Desktop metadata. charging_mode: Billing type of the package. 1 indicates yearly/monthly billing, and 0 indicates pay-per-use billing. image_name: Name of the image used to create a desktop. metering.image_id: Image ID. metering.resourcespeccode: Desktop resource code. metering.resourcetype: Desktop resource type. os_bit: Number of bits of the OS. The value can be 32 or 64. os_type: OS type. The value can be Linux, Windows, or Others. desktop_os_version: OS version.
flavor	FlavorInfo object	Product information.
status	String	Desktop status.
task_status	String	Task status. scheduling: The task is being created and scheduled. block_device_mapping: The disk is being prepared. networking: The network is being prepared. spawning: The task is being created internally. rebooting: The system is being restarted. reboot_pending: The task of system restart is being delivered. reboot_started: The system is being restarted internally. rebooting_hard: The system is being forcibly restarted. reboot_pending_hard: The task of forcible restart is being delivered. reboot_started_hard: The system is being forcibly restarted internally. rebuilding: The system is being rebuilt. rebuild_block_device_mapping: The system is being rebuilt and disks are being prepared. rebuild_spawning: The system is being rebuilt internally. migrating: Live migration is being performed. resize_prep: The flavor is being adjusted. resize_migrating: The flavor is being adjusted and the migration is in progress. resize_migrated: The flavor is being adjusted and the migration has been completed. resize_finish: The flavor has been adjusted. resize_reverting: The flavor is being rolled back. powering-off: The system is being powered off. powering-on: The system is being powered on. deleting: Deletion is being performed. deleteFailed: Deletion failed.
created	String	Time when a desktop is created.
security_groups	Array of SecurityGroup objects	Desktop security group.
login_status	String	Login status of a desktop. UNREGISTER: The desktop is not registered. After the desktop is started, it is automatically registered. After the desktop is shut down, it is unregistered. REGISTERED: The desktop has been registered and is waiting for user connections. CONNECTED: A user has logged in to a desktop and is using it. DISCONNECTED: The desktop is disconnected from the client because the client window is closed or the networking between the client and desktop is interrupted.
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.
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. 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.
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.
internet_mode	String	Network access mode. NAT: indicates the NAT Internet access mode EIP: indicates the EIP Internet access mode BOTH: Both the Internet and EIP access modes are supported.
is_attaching_eip	Boolean	Specifies whether an EIP is being bound to the desktop.
attach_state	String	Indicates the assignment status. ATTACHED: assigned. UNATTACH: Unassigned. Association is not performed. DEATTACHED: Unassigned. ATTACHING: Assigning. DEATTACHING: Unassigning. ATTACHFAIL: Assignment failed. DEATTACHFAIL: Unassignment failed. WAITING: Waiting for assignment. It describes the intermediate state between batch assignment (unassignment) and transfers to assignment (unassignment). It facilitates the state independence of a single association process. ATTACH_FAIL_CAN_ATTACH_AGAIN: Assignment failed and re-assignment is allowed. DEATTACH_FAIL_CAN_DEATTACH_AGAIN: Unassignment failed and re-unassignment is allowed.
enterprise_project_id	String	Enterprise project ID.

**Table 6** AddressInfo
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

**Table 7** FlavorInfo
Parameter	Type	Description
id	String	Flavor ID of the desktop.
links	Array of FlavorLinkInfo objects	Shortcut link marker information of the corresponding desktop flavor.

**Table 8** FlavorLinkInfo
Parameter	Type	Description
rel	String	Shortcut link marker name.
hrel	String	Corresponding shortcut link.

**Table 9** SecurityGroup
Parameter	Type	Description
id	String	Security group ID.

**Table 10** AttachInstancesUserInfo
Parameter	Type	Description
user_id	String	User ID.
user_name	String	User to which a desktop belongs. After a desktop is assigned, the user can log in to the desktop. Only uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_) are allowed. When the domain type is LITE_AD, the value contains 1 to 20 characters starting with a lowercase or uppercase letter. When the domain type is LOCAL_AD, the value contains 1 to 20 characters starting with a lowercase or uppercase letter or digit.
user_group	String	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.

**Table 11** VolumeDetail
Parameter	Type	Description
type	String	Desktop data disk type, which must be the same as the disk type provided by the system. SAS: High I/O SSD: Ultra-high I/O
size	Integer	Disk capacity in GB.
device	String	Directory to which the disk is mounted.
id	String	Unique ID of the disk table.
volume_id	String	Disk ID.
create_time	String	Time when the disk is created.
display_name	String	Disk name.

**Table 12** ProductInfo
Parameter	Type	Description
product_id	String	Product ID.
flavor_id	String	Specifications ID.
type	String	Product type. BASE: basic product package. OS is the only commercial software product in the package. Only this type of package can be used for private images.
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.

**Table 13** Tag
Parameter	Type	Description
key	String	Specifies the key of a tag that cannot be empty 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 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code, which is returned upon failure.
error_msg	String	Error description.

Status code: 401

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

Status code: 403

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

Status code: 404

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

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 description.

Example Requests

/v2/0bec5db98280d2d02fd6c00c2de791ce/desktops/detail

Example Responses

Status code: 200

Response to the request for querying the cloud desktop details list.

{
  "desktops" : [ {
    "desktop_id" : "21616aa6-061d-4b2f-bd83-b230d7a9a14c",
    "computer_name" : "CHENMIN01",
    "addresses" : [ {
      "addr" : "172.16.253.204",
      "version" : "4",
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:2e:41:55",
      "OS-EXT-IPS:type" : "fixed"
    }, {
      "addr" : "10.0.9.55",
      "version" : "4",
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:d5:b3:02",
      "OS-EXT-IPS:type" : "fixed"
    } ],
    "ip_addresses" : [ "172.16.253.204", "10.0.9.55" ],
    "desktop_type" : "DEDICATED",
    "metadata" : {
      "image_name" : "copy_uos-hjg1",
      "metering.resourcespeccode" : "rs3.large.2.linux",
      "charging_mode" : "0",
      "metering.image_id" : "39efed30-a0db-4520-8134-19a086e14c7e",
      "metering.resourcetype" : "1",
      "os_type" : "Linux",
      "os_bit" : "64",
      "desktop_os_version" : "20"
    },
    "flavor" : {
      "id" : "rs3.large.2",
      "links" : [ ]
    },
    "status" : "ACTIVE",
    "task_status" : "",
    "created" : "2022-01-21T06:57:47.459Z",
    "login_status" : "REGISTERED",
    "user_name" : "chenmin",
    "product_id" : "workspace.k.large2.uosv20pro",
    "root_volume" : {
      "type" : "SAS",
      "size" : 90,
      "device" : "/dev/vda",
      "id" : "e4406c227a8711ecaf56fa163ed8e03f",
      "volume_id" : "91b9457c-ef61-4058-9e82-c86b35f15934",
      "create_time" : "2022-03-28T00:00:00Z",
      "display_name" : "workspace002"
    },
    "data_volumes" : [ {
      "type" : "SATA",
      "size" : 10,
      "device" : "/dev/vdc",
      "id" : "fd4597cb80b311ecaf56fa163ed8e03f",
      "volume_id" : "230432f1-44a4-47a1-862e-cd0b65c04bd1",
      "create_time" : "2022-03-28T00:00:00Z",
      "display_name" : "workspace001"
    } ],
    "user_group" : "default",
    "availability_zone" : "cn-north-5a",
    "site_type" : "IES",
    "site_name" : "Edge station.",
    "product" : {
      "product_id" : "workspace.k.large2.uosv20pro",
      "flavor_id" : "rs3.large.2",
      "type" : "BASE",
      "cpu" : "2",
      "memory" : "3072",
      "descriptions" : "CPU:2vCPUs,Memory:4GB",
      "charge_mode" : "0"
    },
    "os_version" : "20",
    "sid" : "1f60adc1-941c-48b8-b5c8-64948329b7cb",
    "order_id" : "CS2201211457G0PUY",
    "tags" : [ ],
    "in_maintenance_mode" : false
  }, {
    "desktop_id" : "e7a27bad-323f-4ec8-9afe-e53d00171ba9",
    "computer_name" : "HJG01",
    "addresses" : [ {
      "addr" : "172.16.242.253",
      "version" : "4",
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:20:14:00",
      "OS-EXT-IPS:type" : "fixed"
    }, {
      "addr" : "10.0.5.247",
      "version" : "4",
      "OS-EXT-IPS-MAC:mac_addr" : "fa:16:3e:29:c4:3f",
      "OS-EXT-IPS:type" : "fixed"
    } ],
    "ip_addresses" : [ "172.16.242.253", "10.0.5.247" ],
    "desktop_type" : "DEDICATED",
    "metadata" : {
      "image_name" : "UOS_20_PRO_chenmin",
      "metering.resourcespeccode" : "rs3.xlarge.2.linux",
      "charging_mode" : "0",
      "metering.image_id" : "6fe1cd9e-e997-4c02-8257-395c28de49b3",
      "metering.resourcetype" : "1",
      "os_type" : "Linux",
      "os_bit" : "64",
      "desktop_os_version" : "20"
    },
    "flavor" : {
      "id" : "rs3.xlarge.2",
      "links" : [ ]
    },
    "status" : "ACTIVE",
    "task_status" : "",
    "created" : "2022-01-18T07:53:25.815Z",
    "login_status" : "REGISTERED",
    "user_name" : "hjg",
    "product_id" : "workspace.k.large4.uosv20pro",
    "root_volume" : {
      "type" : "SAS",
      "size" : 80,
      "device" : "/dev/vda",
      "id" : "1791c183783411ecaf56fa163ed8e03f",
      "volume_id" : "703b49d6-794e-4474-a256-fb695fb46466"
    },
    "user_group" : "sudo",
    "availability_zone" : "cn-north-5a",
    "site_type" : "CENTER",
    "site_name" : "Central site of CN North-Beijing4",
    "product" : {
      "product_id" : "workspace.k.large4.uosv20pro",
      "flavor_id" : "rs3.xlarge.2",
      "type" : "BASE",
      "cpu" : "4",
      "memory" : "7168",
      "descriptions" : "CPU:4vCPUs,Memory:7GB",
      "charge_mode" : "0"
    },
    "os_version" : "20",
    "sid" : "3f5cdbd5-9652-4339-9aab-70d0644f8abc",
    "order_id" : "CS220118155365RYV",
    "tags" : [ ],
    "in_maintenance_mode" : true
  } ],
  "total_count" : 2
}

Status Codes

Status Code	Description
200	Response to the request for querying the cloud desktop details list.
400	The request cannot be understood by the server due to malformed syntax.
401	Authentication failed.
403	You do not have required permissions.
404	No resource found.
500	An internal service error occurred. For details about the error code, see the error code description.