Help Center/ Workspace/ API Reference/ Workspace APIs/ Desktop/ Queries details about one desktop.
Updated on 2024-01-10 GMT+08:00

Queries details about one desktop.

Function

Queries details about a specified desktop by ID.

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/{desktop_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

desktop_id

Yes

String

Desktop ID.

Request Parameters

Table 2 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 3 Response body parameters

Parameter

Type

Description

desktop

DesktopDetailInfo object

Desktop details.

Table 4 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 5 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 6 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 7 FlavorLinkInfo

Parameter

Type

Description

rel

String

Shortcut link marker name.

hrel

String

Corresponding shortcut link.

Table 8 SecurityGroup

Parameter

Type

Description

id

String

Security group ID.

Table 9 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 10 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 11 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 12 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 13 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 14 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 15 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 16 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 17 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/a130ab3a-72bf-4b71-baa9-af4987c8e338

Example Responses

Status code: 200

Normal.

{
  "desktop" : [ {
    "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",
    "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" : [ ]
  } ]
}

Status Codes

Status Code

Description

200

Normal.

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.

Error Codes

See Error Codes.