Use DescribeDesktops to query details of cloud computers - Elastic Desktop Service - Alibaba Cloud - Elastic Desktop Service

Query EDS instance details.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecd:DescribeDesktops

get

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call the DescribeRegions operation to query the regions supported by Elastic Desktop Service.	cn-hangzhou
GroupId	string	No	The ID of the desktop pool.	dg-boyczi8enfyc5****
DesktopStatus	string	No	The status of the cloud desktop. Valid values: Stopped : The desktop is stopped. Starting : The desktop is starting. Rebuilding : The desktop is being rebuilt. Running : The desktop is running. Stopping : The desktop is stopping. Expired : The desktop has expired. Deleted : The desktop is deleted. Pending : The desktop is being created.	Running
MaxResults	integer	No	The number of entries to return on each page.	10
NextToken	string	No	The token that marks the start of the next page of results. If you do not specify this parameter in your first request, all results are returned. If the `NextToken` value in the response is empty, no more results are available. Maximum value: 100 Default value: 10	caeba0bbb2be03f84eb48b699f0a4883
UserName	string	No	The username.	Alice
DesktopName	string	No	The name of the cloud desktop.	DemoComputer01
DirectoryId	string	No	The ID of the directory, which is the same as the office network ID.	cn-hangzhou+dir-363353****
OfficeSiteId	string	No	The ID of the office network.	cn-hangzhou+dir-363353****
OfficeSiteName	string	No	The name of the office network.	default
PolicyGroupId	string	No	The ID of the policy.	system-all-enabled-policy
ChargeType	string	No	The billing method of the cloud desktop. Valid values: PostPaid : pay-as-you-go (default) PrePaid : subscription	PostPaid
ExpiredTime	string	No	The expiration time of the subscription cloud desktop.	2022-12-31T15:59:59Z
ProtocolType	string	No	The protocol type. Valid values: HDX : HDX protocol ASP : The proprietary ASP protocol from Alibaba Cloud. (Recommended)	ASP
DesktopId	array	No	The IDs of the cloud desktops. You can specify up to 100 IDs.	ecd-gx2x1dhsmucyy****
	string	No	A cloud desktop ID.	ecd-gx2x1dhsmucyy****
EndUserId	array	No	The authorized users of the cloud desktops. You can specify up to 100 users.	alice
	string	No	The ID of an authorized user.	alice
ExcludedEndUserId	array	No	The authorized users to exclude. You can specify up to 100 users. Note Only one user can connect to and use the cloud desktop at a time.	andy
	string	No	An authorized user to exclude.	andy
FilterDesktopGroup	boolean	No	Specifies whether to exclude pooled desktops. Valid values: true : Excludes pooled desktops. (Default) false : Includes pooled desktops.	false
ManagementFlag	string	No	The management flag. Valid values: Migrating : The cloud desktop is being migrated. Updating : The cloud desktop is being upgraded or downgraded. NoFlag : The cloud desktop has no management flag.	NoFlag
QueryFotaUpdate	boolean	No	Specifies whether to query the image version information of the cloud desktop. Valid values: true : The response includes image upgrade information. false : The response does not include image upgrade information. (Default)	false
Tag	array<object>	No	The tags to filter cloud desktops by. You can use tags to group and manage cloud desktops for easier searching and batch operations. For more information, see Use tags to manage cloud desktops.
	object	No	A tag that consists of a key-value pair. You can add up to 20 tags to a cloud desktop. Each key must map to exactly one value.
Key	string	No	The tag key. If you specify `Tag`, `Key` is required. The key can be up to 128 characters in length. The key cannot start with `aliyun` or `acs:`, contain `http://` or `https://`, or consist of only whitespace.	TestKey
Value	string	No	The tag value. The value can be up to 128 characters in length. The value cannot start with `aliyun` or `acs:` or contain `http://` or `https://`.	TestValue
SnapshotPolicyId	string	No	The ID of the snapshot policy.	sp-hb12mclyne09xw***
OnlyDesktopGroup	boolean	No	Specifies whether to query only pooled desktops.	true
DesktopGroupId	string	No	The ID of the desktop pool. This parameter is ignored if you specify `DesktopId`. If `DesktopId` is not specified, this operation queries all cloud desktops in the specified desktop pool.	dg-2i8qxpv6t1a03****
OsTypes	array	No	The operating system types.
	string	No	The operating system type. Valid values: Linux : Linux Windows : Windows	Windows
DesktopType	string	No	The instance type of the cloud desktop. You can call the DescribeDesktopTypes operation to query the supported instance types.	eds.general.2c8g
ImageId	array	No	A list of image IDs to filter results by.
	string	No	The image ID.	m-2g65ljy3ynrdq****
DesktopStatusList	array	No	A list of cloud desktop statuses to filter results by.
	string	No	The cloud desktop status. Valid values: Stopped : The desktop is stopped. Starting : The desktop is starting. Rebuilding : The desktop is being rebuilt. Running : The desktop is running. Stopping : The desktop is stopping. Expired : The desktop has expired. Deleted : The desktop is deleted. Pending : The desktop is being created.	Stopped
GpuInstanceGroupId	string	No	The ID of the elastic GPU pool.	gp-0bm2iz1v6m6nx****
QosRuleId	string	No	The ID of the network QoS rule.	qos-5605u0gelk200****
SubPayType	string	No	The purchase method of the cloud desktop. Valid values: duration : Duration package (Whitelisted) postPaid : pay-as-you-go monthPackage : Monthly package (120 hours or 250 hours) prePaid : Monthly package (unlimited duration)	monthPackage
ResourceGroupId	string	No	The ID of the resource group.	rg-4hsvzbbmqdzu3s****
FillResourceGroup	boolean	No	Specifies whether to include resource group information in the response.	true
PageNumber	integer	No	The page number.	1
PageSize	integer	No	The number of entries per page.	10
MultiResource	boolean	No	Specifies whether to query multiple resources.	false
IncludeAutoSnapshotPolicy	boolean	No	Specifies whether to include information about automatic snapshot policies in the response.

Response elements

Element	Type	Description	Example
	object	The returned data.
NextToken	string	The token to start the next query. If this parameter is empty, no more results are available.	caeba0bbb2be03f84eb48b699f0a4883
RequestId	string	The request ID.	484256DA-D816-44D2-9D86-B6EE4D5BA78C
TotalCount	integer	The total number of cloud desktops.	1
Desktops	array<object>	The details of the cloud desktops.
	array<object>	Details of a cloud desktop.
CreationTime	string	The time the cloud desktop was created.	2020-11-06T08:28Z
ChargeType	string	The billing method of the cloud desktop. Valid values: PostPaid : pay-as-you-go PrePaid : subscription	PostPaid
DesktopName	string	The name of the cloud desktop.	DemoComputer01
PolicyGroupName	string	The name of the policy.	All enabled policy
SystemDiskSize	integer	Note This parameter is in invitational preview and is not publicly available.	0
PolicyGroupId	string	The ID of the policy.	system-all-enabled-policy
DesktopStatus	string	The status of the cloud desktop.	Running
DesktopType	string	The desktop instance type.	ecd.basic.large
GpuCount	number	The number of GPUs.	1
ProtocolType	string	The protocol type. Valid values: HDX : HDX protocol ASP : Alibaba Cloud's proprietary ASP protocol	ASP
Memory	integer	The memory size, in MiB.	4096
GpuSpec	string	The GPU specification.	NVIDIA T4
ImageId	string	The image ID.	m-4zfb6zj728hhr****
DirectoryId	string	The directory ID. This value is the same as the office site ID (`OfficeSiteId`).	cn-hangzhou+dir-363353****
ManagementFlag	string	The management flag. Valid values: Migrating : The cloud desktop is being migrated. Updating : The specifications of the cloud desktop are being updated. NoFlag : No flags are attached to the cloud desktop.	NoFlag
DataDiskCategory	string	Note This parameter is in invitational preview and is not publicly available.	null
SystemDiskCategory	string	Note This parameter is in invitational preview and is not publicly available.	null
NetworkInterfaceId	string	The ID of the secondary elastic network interface (ENI) that is created by the cloud desktop service for a Resource Access Management (RAM) or an Active Directory (AD) user. This ID cannot be modified.	123456
OfficeSiteId	string	The ID of the office site.	cn-hangzhou+dir-363353****
DataDiskSize	string	Note This parameter is in invitational preview and is not publicly available.	null
DesktopGroupId	string	The ID of the desktop pool that contains the cloud desktop. The default value is `null`.	null
DesktopId	string	The ID of the cloud desktop.	ecd-gx2x1dhsmucyy****
OfficeSiteName	string	The name of the office site.	default
StartTime	string	The time when the cloud desktop was first started.	2020-11-06T08:31Z
DirectoryType	string	Note This parameter is in invitational preview and is not publicly available.	SIMPLE
Cpu	integer	The number of vCPUs.	2
NetworkInterfaceIp	string	The IP address of the secondary elastic network interface (ENI) that is created by the cloud desktop service for a Resource Access Management (RAM) or an Active Directory (AD) user.	192.168.XX.XX
ExpiredTime	string	The expiration time of the subscription cloud desktop.	2021-12-31T15:59Z
OsType	string	The operating system type.	Windows
ConnectionStatus	string	The user's connection status. Valid values: Unknown : Unknown Connected : Connected Disconnected : Disconnected	Disconnected
BundleId	string	The ID of the desktop template.	b-2g65ljy4291vl****
BundleName	string	The name of the desktop template.	TemplateName
OfficeSiteType	string	The account type of the office site. Valid values: SIMPLE : convenience account AD_CONNECTOR : enterprise AD account	SIMPLE
HostName	string	The host name.	testName
Disks	array<object>	The details of the disks.
	object	Details of a disk.
DiskType	string	The type of the disk. Valid values: SYSTEM : system disk DATA : data disk	SYSTEM
DiskId	string	The ID of the disk.	d-jedbpr4sl9l37****
DiskSize	integer	The size of the disk, in GiB.	80
PerformanceLevel	string	The performance level of the Enhanced SSD (ESSD). This parameter is returned only for ESSD cloud disks. For more information about the differences between performance levels, see ESSD cloud disks. Valid values: PL1 : PL1 PL0 : PL0 PL3 : PL3 PL2 : PL2	PL0
DiskCategory	string	The category of the disk. cloud_efficiency (ultra disk) cloud_auto (ESSD AutoPL disk) cloud_essd (Enhanced SSD (ESSD), available for specific instance types only) Valid values: cloud_efficiency : ultra disk cloud_auto : AutoPL disk cloud_essd : Enhanced SSD (ESSD). This disk category is available only for specific desktop instance types.	cloud_auto
Tags	array<object>	A list of tags attached to the cloud desktop.
	object	A tag.
Key	string	The tag key.	TestKey
Value	string	The tag value.	TestValue
Sessions	array<object>	A list of sessions on the cloud desktop.
	object	A session on the cloud desktop.
EndUserId	string	The ID of the user connected in this session.	29615820929547****
EstablishmentTime	string	The time the session was established.	2021-03-07T08:23Z
ExternalUserName	string	The username of the external user.	Testname
EndUserIds	array	The IDs of users authorized to use the cloud desktop.
	string	The ID of an authorized user.	alice
DowngradeQuota	integer	The remaining number of times the cloud desktop specifications can be downgraded.	3
DowngradedTimes	integer	The number of times the cloud desktop specifications have been downgraded.	0
GpuCategory	integer	Indicates whether the cloud desktop is a GPU-accelerated desktop.	0
GpuDriverVersion	string	The version of the GPU driver.	null
ZoneType	string	The zone type. Default value: `AvailabilityZone`. This value indicates a standard availability zone.	AvailabilityZone
FotaUpdate	object	The image update information for the cloud desktop.
CurrentAppVersion	string	The current image version of the cloud desktop.	0.0.0-D-20220102.000000
NewAppVersion	string	The image version to which the cloud desktop can be upgraded.	0.0.0-R-20220307.190736
ReleaseNote	string	The release notes of the new image version.	测试升级包03-07
Size	integer	The size of the installation package for the new image version, in KB.	108815097
ReleaseNoteEn	string	The release notes in English.	What's new
ReleaseNoteJp	string	The release notes in Japanese.	リリースノート
Progress	string	The creation progress of the cloud desktop.	100%
VolumeEncryptionEnabled	boolean	Indicates whether disk encryption is enabled.	false
VolumeEncryptionKey	string	The ID of the Key Management Service (KMS) key used for disk encryption. You can call the ListKeys operation to obtain the key ID.	08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
OfficeSiteVpcType	string	The VPC (Virtual Private Cloud) type of the office site. Valid values: standard : Standard customized : Customized basic : Basic	basic
Platform	string	The operating system platform. Valid values: Ubuntu : Ubuntu Windows Server 2022 : Windows Server 2022 UOS : UOS CentOS : CentOS Windows Server 2019 : Windows Server 2019 Windows Server 2016 : Windows Server 2016	Ubuntu
SessionType	string	The session type. Valid values: SINGLE_SESSION : single-session MULTIPLE_SESSION : multi-session	SINGLE_SESSION
ManagementFlags	array	The management flags.
	string	The management status of the cloud desktop. Valid values: Migrating : The office site is being migrated. Hibernated : The cloud desktop is in hibernation. UnderMaintenance : The cloud desktop is in maintenance mode. MigratingProtocol : The protocol is being migrated. EnterMaintenance : The cloud desktop is entering maintenance mode. WakingUp : The cloud desktop is waking up. Updating : The cloud desktop is being updated. NoFlag : No flags are attached to the cloud desktop. Assigning : A user is being assigned to the cloud desktop. Hibernating : The cloud desktop is hibernating.	["NoFlag"]
SnapshotPolicyId	string	The ID of the snapshot policy.	sp-gi007jgyc3kce****
SnapshotPolicyName	string	The name of the snapshot policy.	testSnapshotName
BindAmount	integer	The maximum number of concurrent sessions allowed for each cloud desktop in a multi-session desktop pool.	2
PolicyGroupIdList	array	The IDs of the attached policies.
	string	The ID of the policy.	pg-dasffjkdf*****
PolicyGroupNameList	array	The names of the policies.
	string	The name of the policy.	测试策略01
HibernationOptionsConfigured	boolean	Note This parameter is in invitational preview and is not publicly available.	true
SupportHibernation	boolean	Indicates whether hibernation is supported.	true
HibernationBeta	boolean	Note This parameter is in invitational preview and is not publicly available.	true
ResourceGroups	array<object>	Information about the resource groups.
	object	Information about a resource group.
Name	string	The name of the resource group.	资源组01
Id	string	The ID of the resource group.	rg-4hsvzbbmqdzu3s****
StandardStartTime	string
OsUpdate	object
CheckId	string
PackageCount	integer
Packages	array<object>
	object
Kb	string
Title	string
Description	string
IsLdap	boolean
DomainType	string
SerialNumber	string
AccountType	string
EntraDomainName	string
EnvType	string
EnvId	string
PageNumber	integer	分页查询时，当前页的页码。	1
PageSize	integer	分页查询时，每页最大行数。	10

Examples

Success response

JSON format

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "RequestId": "484256DA-D816-44D2-9D86-B6EE4D5BA78C",
  "TotalCount": 1,
  "Desktops": [
    {
      "CreationTime": "2020-11-06T08:28Z",
      "ChargeType": "PostPaid",
      "DesktopName": "DemoComputer01",
      "PolicyGroupName": "All enabled policy",
      "SystemDiskSize": 0,
      "PolicyGroupId": "system-all-enabled-policy",
      "DesktopStatus": "Running",
      "DesktopType": "ecd.basic.large",
      "GpuCount": 1,
      "ProtocolType": "ASP",
      "Memory": 4096,
      "GpuSpec": "NVIDIA T4",
      "ImageId": "m-4zfb6zj728hhr****",
      "DirectoryId": "cn-hangzhou+dir-363353****",
      "ManagementFlag": "NoFlag",
      "DataDiskCategory": "null",
      "SystemDiskCategory": "null",
      "NetworkInterfaceId": "123456",
      "OfficeSiteId": "cn-hangzhou+dir-363353****",
      "DataDiskSize": "null",
      "DesktopGroupId": "null",
      "DesktopId": "ecd-gx2x1dhsmucyy****",
      "OfficeSiteName": "default",
      "StartTime": "2020-11-06T08:31Z",
      "DirectoryType": "SIMPLE",
      "Cpu": 2,
      "NetworkInterfaceIp": "192.168.XX.XX",
      "ExpiredTime": "2021-12-31T15:59Z",
      "OsType": "Windows",
      "ConnectionStatus": "Disconnected",
      "BundleId": "b-2g65ljy4291vl****",
      "BundleName": "TemplateName",
      "OfficeSiteType": "SIMPLE",
      "HostName": "testName",
      "Disks": [
        {
          "DiskType": "SYSTEM",
          "DiskId": "d-jedbpr4sl9l37****",
          "DiskSize": 80,
          "PerformanceLevel": "PL0",
          "DiskCategory": "cloud_auto"
        }
      ],
      "Tags": [
        {
          "Key": "TestKey",
          "Value": "TestValue"
        }
      ],
      "Sessions": [
        {
          "EndUserId": "29615820929547****",
          "EstablishmentTime": "2021-03-07T08:23Z",
          "ExternalUserName": "Testname"
        }
      ],
      "EndUserIds": [
        "alice"
      ],
      "DowngradeQuota": 3,
      "DowngradedTimes": 0,
      "GpuCategory": 0,
      "GpuDriverVersion": "null",
      "ZoneType": "AvailabilityZone",
      "FotaUpdate": {
        "CurrentAppVersion": "0.0.0-D-20220102.000000",
        "NewAppVersion": "0.0.0-R-20220307.190736",
        "ReleaseNote": "测试升级包03-07",
        "Size": 108815097,
        "ReleaseNoteEn": "What's new",
        "ReleaseNoteJp": "リリースノート"
      },
      "Progress": "100%",
      "VolumeEncryptionEnabled": false,
      "VolumeEncryptionKey": "08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****",
      "OfficeSiteVpcType": "basic",
      "Platform": "Ubuntu",
      "SessionType": "SINGLE_SESSION",
      "ManagementFlags": [
        "[\"NoFlag\"]"
      ],
      "SnapshotPolicyId": "sp-gi007jgyc3kce****",
      "SnapshotPolicyName": "testSnapshotName",
      "BindAmount": 2,
      "PolicyGroupIdList": [
        "pg-dasffjkdf*****"
      ],
      "PolicyGroupNameList": [
        "测试策略01"
      ],
      "HibernationOptionsConfigured": true,
      "SupportHibernation": true,
      "HibernationBeta": true,
      "ResourceGroups": [
        {
          "Name": "资源组01",
          "Id": "rg-4hsvzbbmqdzu3s****"
        }
      ],
      "StandardStartTime": "",
      "OsUpdate": {
        "CheckId": "",
        "PackageCount": 0,
        "Packages": [
          {
            "Kb": "",
            "Title": "",
            "Description": ""
          }
        ]
      },
      "IsLdap": false,
      "DomainType": "",
      "SerialNumber": "",
      "AccountType": "",
      "EntraDomainName": "",
      "EnvType": "",
      "EnvId": ""
    }
  ],
  "PageNumber": 1,
  "PageSize": 10
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.