DescribeDesktops-阿里云帮助中心

Query the details of your cloud computers.

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
BusinessChannel	string	No	The region ID. Call DescribeRegions to list regions that support Elastic Desktop Service (EDS).
RegionId	string	Yes	The computer pool ID.	cn-hangzhou
GroupId	string	No	The cloud computer status.	dg-boyczi8enfyc5****
DesktopStatus	string	No	The number of entries to return on each page in a paged query. Maximum value: 100. Default value: 10 Valid values: Stopped : Stopped Starting : Starting Rebuilding : Rebuilding Running : Running Stopping : Stopping Expired : Expired Deleted : Deleted Pending : Pending	Running
MaxResults	integer	No	The token that starts the next query. An empty NextToken means no more results.	10
NextToken	string	No	The user name.	caeba0bbb2be03f84eb48b699f0a4883
UserName	string	No	The desktop name.	Alice
DesktopName	string	No	The directory ID. This is the same as the office site ID.	DemoComputer01
DirectoryId	string	No	The office site ID.	cn-hangzhou+dir-363353****
OfficeSiteId	string	No	The name of the office network.	cn-hangzhou+dir-363353****
OfficeSiteName	string	No	The desktop policy ID.	default
PolicyGroupId	string	No	The billing method for the desktop.	system-all-enabled-policy
ChargeType	string	No	The expiration time for subscription desktops. Valid values: PostPaid : Pay-as-you-go [default] PrePaid : Subscription	PostPaid
ExpiredTime	string	No	The protocol type.	2022-12-31T15:59:59Z
ProtocolType	string	No	The desktop IDs. You can specify 1 to 100 IDs. Valid values: HDX : HDX protocol ASP : Alibaba Cloud proprietary ASP protocol [recommended]	ASP
DesktopId	array	No	The list of authorized users for the desktop. You can specify 1 to 100 users. Note Only one user can connect to and use the desktop at a time.	ecd-gx2x1dhsmucyy****
	string	No	The authorized user for the desktop.	ecd-gx2x1dhsmucyy****
EndUserId	array	No	The list of authorized users to exclude from the desktop. You can specify 1 to 100 users.	alice
	string	No	The authorized user to exclude from the desktop.	alice
ExcludedEndUserId	array	No	Whether to exclude pooled desktops (desktops in a computer pool).	andy
	string	No	The authorized user to exclude from the desktop.	andy
FilterDesktopGroup	boolean	No	The management flag. Valid values: true : Exclude pooled desktops [default] false : Do not exclude pooled desktops	false
ManagementFlag	string	No	Whether to query image version information for the desktop. Valid values: Migrating : Migrating Updating : Upgrading or downgrading NoFlag : No flag	NoFlag
QueryFotaUpdate	boolean	No	The list of tags. Each tag is a key-value pair used to label resources. Use tags to group and manage desktops, making them easier to search and operate on in bulk. For more information, see Manage cloud computers by using tags. Valid values: true : Query image upgrade information false : Do not query image upgrade information [default]	false
Tag	array<object>	No	The snapshot policy ID.
	object	No	A tag key-value pair. You can assign up to 20 key-value pairs per desktop. Each key must map to exactly one value.
Key	string	No	The tag key. If you specify `Tag`, then `Key` is required. The key can be up to 128 characters long. It cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`. It cannot consist only of whitespace.	TestKey
Value	string	No	The tag value. The value can be up to 128 characters long. It cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	TestValue
SnapshotPolicyId	string	No	Whether to query only pooled desktops (desktops in a computer pool).	sp-hb12mclyne09xw***
OnlyDesktopGroup	boolean	No	The computer pool ID. If you specify `DesktopId`, this parameter is ignored. If `DesktopId` is empty, the system uses `DesktopGroupId` to retrieve all desktop IDs in the pool.	true
DesktopGroupId	string	No	The operating system type.	dg-2i8qxpv6t1a03****
OsTypes	array	No	The desktop instance type. Call DescribeDesktopTypes to list supported instance types.
	string	No	The operating system type. Valid values: Linux : Linux Windows : Windows	Windows
DesktopType	string	No	The list of image IDs.	eds.general.2c8g
ImageId	array	No	The list of desktop statuses.
	string	No	The desktop status.	m-2g65ljy3ynrdq****
DesktopStatusList	array	No	The elastic GPU pool ID.
	string	No	The desktop status. Valid values: Stopped : Stopped Starting : Starting Rebuilding : Rebuilding Running : Running Stopping : Stopping Expired : Expired Deleted : Deleted Pending : Pending	Stopped
GpuInstanceGroupId	string	No	The public network bandwidth throttling rule ID.	gp-0bm2iz1v6m6nx****
QosRuleId	string	No	The purchase method for the desktop.	qos-5605u0gelk200****
SubPayType	string	No	The enterprise resource group ID. Valid values: duration : Duration package [whitelist] postPaid : Pay-as-you-go monthPackage : Monthly package (120 hours or 250 hours) prePaid : Monthly package (unlimited duration)	monthPackage
ResourceGroupId	string	No	Whether to query enterprise resource group information.	rg-4hsvzbbmqdzu3s****
FillResourceGroup	boolean	No	The page number of the current page in a paged query.	true
PageNumber	integer	No	The maximum number of entries to return on each page in a paged query.	1
PageSize	integer	No	Whether multiple resources exist.	10
MultiResource	boolean	No		false
IncludeAutoSnapshotPolicy	boolean	No

Response elements

Element	Type	Description	Example
	object	The response object.
NextToken	string	The token that starts the next query. An empty NextToken means no more results.	caeba0bbb2be03f84eb48b699f0a4883
RequestId	string	The request ID.	484256DA-D816-44D2-9D86-B6EE4D5BA78C
TotalCount	integer	The total number of desktops.	1
Desktops	array<object>	Details about the desktops.
	array<object>	Details about the desktops.
CreationTime	string	The time when the desktop was created.	2020-11-06T08:28Z
ChargeType	string	The billing method for the desktop. Valid values: PostPaid : Pay-as-you-go [default] PrePaid : Subscription	PostPaid
DesktopName	string	The desktop name.	DemoComputer01
PolicyGroupName	string	The policy name.	All enabled policy
SystemDiskSize	integer	Note This parameter is in invitational preview and is not available for use.	0
PolicyGroupId	string	The desktop policy ID.	system-all-enabled-policy
DesktopStatus	string	The desktop status.	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 proprietary ASP protocol	ASP
Memory	integer	The memory size. Unit: MiB.	4096
GpuSpec	string	The GPU specification.	NVIDIA T4
ImageId	string	The image ID.	m-4zfb6zj728hhr****
DirectoryId	string	The directory ID. This is the same as the office site ID (OfficeSiteId).	cn-hangzhou+dir-363353****
ManagementFlag	string	The management flag. Valid values: Migrating : Migrating Updating : Upgrading or downgrading NoFlag : No flag	NoFlag
DataDiskCategory	string	Note This parameter is in invitational preview and is not available for use.	null
SystemDiskCategory	string	Note This parameter is in invitational preview and is not available for use.	null
NetworkInterfaceId	string	The ID of the secondary ENI created by the desktop service under a RAM or AD user. This value cannot be modified.	123456
OfficeSiteId	string	The office site ID.	cn-hangzhou+dir-363353****
DataDiskSize	string	Note This parameter is in invitational preview and is not available for use.	null
DesktopGroupId	string	The computer pool ID that the desktop belongs to. Default value: `null`.	null
DesktopId	string	The desktop ID.	ecd-gx2x1dhsmucyy****
OfficeSiteName	string	The office site name.	default
StartTime	string	The first time the desktop started.	2020-11-06T08:31Z
DirectoryType	string	Note This parameter is in invitational preview and is not available for use.	SIMPLE
Cpu	integer	The number of vCPUs.	2
NetworkInterfaceIp	string	The IP address of the secondary ENI created by the desktop service under a RAM or AD user.	192.168.XX.XX
ExpiredTime	string	The expiration time for subscription desktops.	2021-12-31T15:59Z
OsType	string	The operating system type.	Windows
ConnectionStatus	string	The connection status of the user. Valid values: Unknown : Unknown Connected : Connected Disconnected : Disconnected	Disconnected
BundleId	string	The desktop template ID used by the desktop.	b-2g65ljy4291vl****
BundleName	string	The desktop template name used by the desktop.	TemplateName
OfficeSiteType	string	The account system type for the office site. Valid values: SIMPLE : Convenience account AD_CONNECTOR : Enterprise AD account	SIMPLE
HostName	string	The host name.	testName
Disks	array<object>	Disk information.
	object	Disk information.
DiskType	string	The disk type. Valid values: SYSTEM : System disk DATA : Data disk	SYSTEM
DiskId	string	The disk ID.	d-jedbpr4sl9l37****
DiskSize	integer	The disk size. Unit: GiB.	80
PerformanceLevel	string	The performance level of ESSD disks, if the disk uses ESSD. For differences between performance levels, see ESSDs. Valid values: PL1 : PL1 PL0 : PL0 PL3 : PL3 PL2 : PL2	PL0
DiskCategory	string	The disk type. cloud_efficiency (ultra disk) cloud_auto (extreme disk) cloud_essd (enhanced SSD disk, supported only on select instance types) Valid values: cloud_efficiency : Ultra disk cloud_auto : Extreme disk cloud_essd : Enhanced SSD disk, supported only on select instance types	cloud_auto
Tags	array<object>	Tag information.
	object	Tag information.
Key	string	The tag key.	TestKey
Value	string	The tag value.	TestValue
Sessions	array<object>	Session information for the desktop user.
	object	Session information for the desktop user.
EndUserId	string	The user ID connected to the desktop.	29615820929547****
EstablishmentTime	string	The time when the desktop session was established.	2021-03-07T08:23Z
ExternalUserName	string	The external user name.	Testname
EndUserIds	array	The authorized user IDs for the desktop.
	string	The authorized user ID for the desktop.	alice
DowngradeQuota	integer	The number of times the desktop can be downgraded.	3
DowngradedTimes	integer	The number of times the desktop has been downgraded.	0
GpuCategory	integer	Whether the desktop is a GPU desktop.	0
GpuDriverVersion	string	The GPU driver version for the desktop.	null
ZoneType	string	The type of zone to query. Default value: `AvailabilityZone`, which refers to standard cloud availability zones.	AvailabilityZone
FotaUpdate	object	The image version information for the desktop.
CurrentAppVersion	string	The current image version number of the desktop.	0.0.0-D-20220102.000000
NewAppVersion	string	The image version number to which the desktop can be upgraded.	0.0.0-R-20220307.190736
ReleaseNote	string	The description of the upgradeable image version.	测试升级包03-07
Size	integer	The size of the upgradeable version installation package. Unit: KB.	108815097
ReleaseNoteEn	string	The English description of the upgradeable version.	What's new
ReleaseNoteJp	string	The Japanese description of the upgradeable version.	リリースノート
Progress	string	The creation progress of the desktop.	100%
VolumeEncryptionEnabled	boolean	Whether disk encryption is enabled.	false
VolumeEncryptionKey	string	The ID of the KMS key used when disk encryption is enabled. You can obtain it through the ListKeys interface.	08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
OfficeSiteVpcType	string	The VPC type of the office site. Valid values: standard : Standard customized : Customized basic : Basic	basic
Platform	string	The operating system platform information. 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 desktop. Valid values: Migrating : Migrating office network Hibernated : Hibernated UnderMaintenance : In maintenance mode MigratingProtocol : Migrating protocol EnterMaintenance : Entering maintenance mode WakingUp : Waking up Updating : Upgrading NoFlag : Stateless Assigning : Assigning user Hibernating : Hibernating	["NoFlag"]
SnapshotPolicyId	string	The snapshot policy ID.	sp-gi007jgyc3kce****
SnapshotPolicyName	string	The snapshot policy name.	testSnapshotName
BindAmount	integer	The number of concurrent sessions allowed per desktop in a multi-session computer pool.	2
PolicyGroupIdList	array	The collection of desktop policy IDs.
	string	The desktop policy ID.	pg-dasffjkdf*****
PolicyGroupNameList	array	The list of desktop policy names.
	string	The desktop policy name.	测试策略01
HibernationOptionsConfigured	boolean	Note This parameter is in invitational preview and is not available for use.	true
SupportHibernation	boolean	Whether hibernation is supported.	true
HibernationBeta	boolean	Note This parameter is in invitational preview and is not available for use.	true
ResourceGroups	array<object>	The list of enterprise resource group information.
	object	The enterprise resource group information.
Name	string	The enterprise resource group name.	资源组01
Id	string	The enterprise resource group ID.	rg-4hsvzbbmqdzu3s****
StandardStartTime	string	The standard start time.
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
AgentProviderList	array
	string
PageNumber	integer	The page number of the current page in a paged query.	1
PageSize	integer	The maximum number of entries to return on each page in a paged query.	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": "",
      "AgentProviderList": [
        ""
      ]
    }
  ],
  "PageNumber": 1,
  "PageSize": 10
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.