DocsICP FilingConsole
Documentation

CreateDesktops

Updated at:
Copy as MD
Product
My Favorites

Creates one or more cloud desktops. If user information is provided during creation, the cloud desktops are directly assigned.

Operation description

Before you create a cloud desktop, complete the following preparations:

Call examples:

Example of request parameters for creating a cloud desktop by using a template

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office network must be created in advance.
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "BundleId": "b-enterprise_office_8c16g_windows2022"
}

Example of creating a cloud desktop without a template

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office network must be created in advance.
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "ImageId": "desktopimage-windows-server-2022-64-asp",
    "SystemDiskSize": "40",
    "DataDiskSize": "0",
    "DefaultLanguage": "zh-CN",
    "DesktopType": "eds.enterprise_office.4c8g"
  }
}

Example of request parameters for creating a monthly hourly package

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office network must be created in advance.
  "PolicyGroupId": "system-all-enabled-policy",
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "ImageId": "desktopimage-windows-server-2022-64-asp",
    "SystemDiskSize": "40",
    "DataDiskSize": "0",
    "DefaultLanguage": "zh-CN",
    "DesktopType": "eds.enterprise_office.4c8g"
  },
  "MonthDesktopSetting": {
    "UseDuration": "120"
  },
  "Period": "1",
  "PeriodUnit": "Month"
}

Example of request parameters for creating an agent resource

{
  "RegionId": "cn-hangzhou",
  "BundleId": "b-openclaw-linux",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office network must be created in advance.
  "ChargeType": "PostPaid",
  "DesktopAttachment": {
    "DesktopType": "cloud.space.4c.8g"
  },
  "PurchaseOptions": {
    "MonthlyCredits": "120"
  },
  "Period": "1",
  "PeriodUnit": "Month"
}

To allow the cloud desktop to automatically execute custom command scripts, you can use the UserCommands field to configure custom commands.

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:CreateDesktops

create

*All Resource

*

 None None

Request parameters

Parameter

Type

Required

Description

Example
RegionId

string

Yes

The region ID. You can call the DescribeRegions operation to query the list of regions supported by WUYING Workspace.

cn-hangzhou
GroupId

string

No

The ID of the cloud desktop pool.

dg-boyczi8enfyc5****
BundleId

string

No

The ID of the cloud desktop template. If you do not specify a template ID, you can complete the creation by specifying the required fields.

b-je9hani001wfn****
DesktopName

string

No

The name of the cloud desktop. The name must meet the following rules:

  • The name can be up to 64 characters in length.

  • The name must start with a letter or a Chinese character, and cannot start with http:// or https://.

  • The name can contain Chinese characters, letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).

DemoComputer01
UserName

string

No

Note

This parameter is not available for use.

username
VpcId

string

No

Note

This parameter is not available for use.

vpc-uf6w8u60n8xbkg5el****
Amount

integer

No

The number of cloud desktops to create. Valid values: 1 to 300. Default value: 1.

1
DirectoryId

string

No

Note

This parameter is not available for use.

cn-hangzhou+dir-300943****
OfficeSiteId

string

No

The ID of the office network.

cn-hangzhou+dir-387822****
PolicyGroupId

string

No

The ID of the policy.

system-all-enabled-policy
ChargeType

string

No

The billing method of the cloud desktop. Valid values:

Valid values:

  • PostPaid :

    PostPaid: pay-as-you-go. Default value.

  • PrePaid :

    PrePaid: subscription.

PrePaid
Period

integer

No

The subscription period of the resource. The unit is specified by PeriodUnit. This parameter takes effect and is required only when ChargeType is set to PrePaid.

  • If PeriodUnit is set to Month, valid values of this parameter are:

    • 1

    • 2

    • 3

    • 6

  • If PeriodUnit is set to Year, valid values of this parameter are:

    • 1

    • 2

    • 3

    • 4

    • 5

1
PeriodUnit

string

No

The time unit for the subscription billing method. Valid values:

Valid values:

  • Month :

    Month: month. Default value.

  • Year :

    Year: year.

Month
AutoPay

boolean

No

Specifies whether to enable automatic payment. Valid values:

Valid values:

  • false :

    false: generates an order without payment. You can log on to the console and pay for the order on the My Orders page in User Center based on the returned order ID.

  • true :

    true: enables automatic payment. Make sure that your account balance is sufficient. Otherwise, an abnormal order is generated. Default value.

false
AutoRenew

boolean

No

Specifies whether to enable auto-renewal. This parameter takes effect only when ChargeType is set to PrePaid. Valid values:

Valid values:

  • false :

    false: disables auto-renewal. Default value.

  • true :

    true: enables auto-renewal. The renewal period is the same as the subscription period.

false
PromotionId

string

No

The ID of the promotional event.

23141
UserAssignMode

string

No

The assignment mode of the cloud desktop. Valid values:

Note

If EndUserId is not specified, the created cloud desktop is not assigned to any user.

Valid values:

  • ALL :

    ALL: assigns the created cloud desktop to each specified user if EndUserId is specified. Default value.

  • PER_USER :

    PER_USER: evenly assigns the created cloud desktops to the specified users if EndUserId is specified. In this case, make sure that the value of Amount is divisible by the number of users specified by EndUserId.

ALL
Hostname

string

No

The custom settings for the hostname of the cloud desktop. This parameter is supported only for cloud desktops whose operating system is Windows in an AD office network.

The hostname must meet the following rules:

  • The hostname must be 2 to 15 characters in length.

  • The hostname can contain letters, digits, and hyphens (-). It cannot start or end with a hyphen, contain consecutive hyphens, or contain only digits.

When you create multiple cloud desktops, you can use the name_prefix[begin_number,bits]name_suffix format to name them in a unified manner. For example, if you set Hostname to ecd-[1,4]-test, the hostname of the first cloud desktop is ecd-0001-test, the hostname of the second cloud desktop is ecd-0002-test, and so on.

  • name_prefix: the prefix of the hostname.

  • [begin_number,bits]: the sequential number in the hostname. begin_number is the starting number. Valid values: 0 to 999999. Default value: 0. bits is the number of digits. Valid values: 1 to 6. Default value: 6.

  • name_suffix: the suffix of the hostname.

testhost
EndUserId

array

No

The list of IDs of authorized users to be added to the cloud desktop. You can specify 1 to 100 user IDs.

123456789

string

No

The ID of the authorized user to be added to the cloud desktop.

  • Only one user can use the cloud desktop at a time.

  • If EndUserId is not specified, the created cloud desktop is not assigned to any user.

alice
Tag

array<object>

No

The tags.

object

No

The tags.

Key

string

No

The tag key. You can specify 1 to 20 tag keys.

TestKey
Value

string

No

The tag value. You can specify 1 to 20 tag values.

TestValue
DesktopNameSuffix

boolean

No

Specifies whether to automatically add a suffix to the cloud desktop name when you create multiple cloud desktops in a batch. Valid values:

Valid values:

  • false :

    false: does not add a suffix.

  • true :

    true: automatically adds a suffix. Default value.

false
DesktopNameModel

object

No

The format of the cloud desktop name.

DesktopNameIsSuffix

boolean

No

Specifies whether to automatically add a suffix to the cloud desktop name when you create multiple cloud desktops in a batch. Default value: true.

true
VolumeEncryptionEnabled

boolean

No

Specifies whether to enable cloud disk encryption. Valid values:

Valid values:

  • false :

    false: disables cloud disk encryption. Default value.

  • true :

    true: enables cloud disk encryption.

false
VolumeEncryptionKey

string

No

The ID of the Key Management Service (KMS) key used when cloud disk encryption is enabled. You can call the ListKeys operation to obtain the key ID.

08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
DesktopMemberIp

string

No

The private IP address of the cloud desktop.

10.0.0.1
UserCommands

array<object>

No

The custom command script data.

object

No

The custom command script data.

Content

string

No

The content of the command.

bmV3LWl0ZW0gZDpcdGVzdF91c2VyX2NvbW1hbmRzLnR4dCAtdHlwZSBm****
ContentEncoding

string

No

The encoding method of the command content. Valid values:

Valid values:

  • Base64 :

    Base64: Base64 encoding.

  • PlainText :

    PlainText: no encoding. Plaintext transmission is used.

Base64
ContentType

string

No

The language type of the command. Valid values:

Valid values:

  • RunPowerShellScript :

    RunPowerShellScript: PowerShell commands for Windows instances.

  • RunShellScript :

    RunShellScript: shell commands for Linux instances.

  • RunBatScript :

    RunBatScript: batch commands for Windows instances.

RunPowerShellScript
BundleModels

array<object>

No

The list of cloud desktop templates.

object

No

The cloud desktop template.

Amount

integer

No

The number of cloud desktops to create. Valid values: 1 to 300. Default value: 0.

1
BundleId

string

No

The ID of the cloud desktop template.

b-je9hani001wfn****
DesktopName

string

No

The name of the cloud desktop. The name must meet the following rules:

  • The name can be up to 64 characters in length.

  • The name must start with a letter or a Chinese character, and cannot start with http:// or https://.

  • The name can contain Chinese characters, letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).

DemoComputer02
EndUserIds

array

No

The list of users to whom the cloud desktop is assigned.

string

No

The username.

alice
Hostname

string

No

The custom settings for the hostname of the cloud desktop. This parameter is supported only for cloud desktops whose operating system is Windows in an AD office network.

The hostname must meet the following rules:

  • The hostname must be 2 to 15 characters in length.

  • The hostname can contain letters, digits, and hyphens (-). It cannot start or end with a hyphen, contain consecutive hyphens, or contain only digits.

When you create multiple cloud desktops, you can use the name_prefix[begin_number,bits]name_suffix format to name them in a unified manner. For example, if you set Hostname to ecd-[1,4]-test, the hostname of the first cloud desktop is ecd-0001-test, the hostname of the second cloud desktop is ecd-0002-test, and so on.

  • name_prefix: the prefix of the hostname.

  • [begin_number,bits]: the sequential number in the hostname. begin_number is the starting number. Valid values: 0 to 999999. Default value: 0. bits is the number of digits. Valid values: 1 to 6. Default value: 6.

  • name_suffix: the suffix of the hostname.

testhost
VolumeEncryptionEnabled

boolean

No

Specifies whether to enable cloud disk encryption. Valid values:

false
VolumeEncryptionKey

string

No

The ID of the Key Management Service (KMS) key used when cloud disk encryption is enabled. You can call the ListKeys operation to obtain the key ID.

08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
DesktopTimers

array<object>

No

The details of the scheduled tasks for the cloud desktop. This parameter is being deprecated. Use the TImerGroupId parameter instead.

object

No

The details of the scheduled task for the cloud desktop.

AllowClientSetting

boolean

No

Specifies whether to allow end users to configure scheduled tasks.

true
CronExpression

string

No

The cron expression of the scheduled task.

Important You must specify the time in UTC. For example, to specify 00:00:00 every day in UTC+8 (Beijing time), pass 0 0 16 ? * 1,2,3,4,5,6,7.

0 40 7 ? * 1,2,3,4,5,6,7
Enforce

boolean

No

Specifies whether to forcibly execute the task.

Valid values:

  • false :

    do not forcibly execute the task.

  • true :

    ignore the cloud desktop and connection status checks and forcibly execute the scheduled task.

true
Interval

integer

No

The time interval, in minutes.

10
OperationType

string

No

The operation type of the scheduled task. Currently, only disconnect scheduled tasks are supported.

Valid values:

  • Hibernate :

    hibernate.

  • Shutdown :

    shut down.

Shutdown
ResetType

string

No

The reset type of the cloud desktop.

Valid values:

  • RESET_TYPE_SYSTEM :

    reset the system cloud disk.

  • RESET_TYPE_BOTH :

    reset the system cloud disk and user disk.

RESET_TYPE_SYSTEM
TimerType

string

No

The type of the scheduled task.

NoOperationReboot
SubnetId

string

No

The subnet ID.

vsw-bp1m*****
MonthDesktopSetting

object

No

The purchase parameters for the monthly hourly package.

BuyerId

integer

No

Note

This field is currently not available for public use.

null
DesktopId

string

No

Note

This field is currently not available for public use.

null
UseDuration

integer

No

The plan selected when purchasing a monthly hourly package. Valid values: 120, 250, and 360.

120
SnapshotPolicyId

string

No

The ID of the Wuying automatic snapshot policy.

sp-28mp6my0l6zow****
ResourceGroupId

string

No

The ID of the Wuying resource group.

rg-3mtuc28rx95lx****
DesktopAttachment

object

No

The parameters for creating a cloud desktop without a template. This parameter is invalid if the BundleId parameter is specified.

DataDiskCategory

string

No

The category of the data cloud disk. The system cloud disk and the data cloud disk must be of the same category. Valid values:

  • cloud_auto: standard SSD

  • cloud_essd: ESSD cloud disk

cloud_auto
DataDiskPerLevel

string

No

The performance level of the ESSD. This parameter is required if you select an ESSD. Valid values:

  • PL0

  • PL1

PL0
DataDiskSize

integer

No

The capacity of the user disk. Unit: GiB. Valid values: 40 to 2040, in increments of 10.

40
DefaultLanguage

string

No

The language. Valid values:

  • zh-CN

  • zh-HK

  • en-US

  • ja-JP

zh-CN
DesktopType

string

No

The specifications of the cloud desktop. You can call the DescribeDesktopTypes operation to query the IDs of supported cloud desktop specifications.

eds.enterprise_office.8c16g
ImageId

string

No

The image ID.

m-39ddhdb0ggzjx*****
SystemDiskCategory

string

No

The category of the system cloud disk. The system cloud disk and the data cloud disk must be of the same category. Valid values:

  • cloud_auto: standard SSD

  • cloud_essd: ESSD cloud disk

cloud_auto
SystemDiskPerLevel

string

No

The performance level of the ESSD. This parameter is required if you select an ESSD. Valid values:

  • PL0

  • PL1

PL0
SystemDiskSize

integer

No

The capacity of the system cloud disk. Unit: GiB. Valid values: 40 to 2040, in increments of 10.

40
TimerGroupId

string

No

The ID of the scheduled task group.

ccg-0caoeogrk9m5****
SavingPlanId

string

No

Note

This field is currently not available for public use.

spn-26c1b7bcrjcI****
ResellerOwnerUid

integer

No

The user ID for resource ownership in the reseller pattern. This parameter is not required in the non-reseller pattern.

1828644634819902
ExtendInfo

string

No

The extended information in JSON string format. This parameter is available only for internal customers.

{}
AppRuleId

string

No

The ID of the application control policy.

bwr-245d4e0e6b7d42f5afa97eb3fbc7e488
QosRuleId

string

No

The ID of the Internet bandwidth throttling rule.

qos-52fqmg6kvyro7zu4l
ChannelCookie

string

No

Note

This field is currently not available for public use.

PBKB1QbqEl2tslEuU6gRrLxvCFBU2M%2FVD0Eru6Oo%2FI9LTU3XQhvq3PGMWarE%2BPJdkNvCqT3blqlRSthNy4A%2BJQ%3D%3D
PurchaseOptions

object

No

The additional parameters for specific purchase types.

CreditPackageAmountSpec

integer

No

The quota of the Wuying credit package.

10000
CreditPackagePeriod

integer

No

The duration of the Wuying credit package.

1
CreditPackagePeriodUnit

string

No

The unit of the credit package duration.

Month
MonthlyCredits

integer

No

The monthly credit package used to select a credit plan when purchasing agent resources. Valid values: 200, 1600, and 4000.

200
OuPath

string

No

The OU path. After this parameter is specified, the cloud desktop joins the corresponding organizational unit (OU) in Active Directory (AD).

test.com/wuyingtest/computers
SubPayType

string

No

The billing method of the cloud desktop. Valid values:

  • prePaid: monthly subscription without a duration limit.

  • postPaid: pay-as-you-go.

  • monthPackage: monthly duration package.

  • jvsAgentPackage: JVS agent duration package.

monthPackage
ReservePoolId

string

No

The ID of compute resource pool (rp-xxx). This parameter is optional. If this parameter is specified, the cloud desktop is created from compute resource pool, computing resources are provided by compute resource pool, and no computing fee order is generated. If the ZoneId parameter is explicitly specified, it must be the same as the zone of compute resource pool.

rp-xxx

Response elements

Element

Type

Description

Example

object

The response information.

DesktopId

array

The IDs of the cloud desktops. If multiple cloud desktops are created in a single call, multiple cloud desktop IDs are returned.

string

The cloud desktop ID.

["ecd-gx2x1dhsmucyy****"]
OrderId

string

The order ID.

Note

This parameter is returned when the ChargeType request parameter is set to PrePaid.

123456789
RequestId

string

The request ID.

1CBAFFAB-B697-4049-A9B1-67E1FC5F****

Examples

Success response

JSON format

{
  "DesktopId": [
    "[\"ecd-gx2x1dhsmucyy****\"]"
  ],
  "OrderId": "123456789",
  "RequestId": "1CBAFFAB-B697-4049-A9B1-67E1FC5F****"
}

Error codes

HTTP status code

Error code

Error message

Description
400 InvalidEncryptionKey.Missing Parameter VolumeEncryptionKey is missing. When the disk encryption function is enabled, the encryption key cannot be empty.
400 InvalidEncryptionKey.NotAuthorized Eds service cannot access the given VolumeEncryptionKey. Unable to access unauthorized encryption keys
400 InvalidEncryptionKey.NotFound The specified VolumeEncryptionKey is not found. The specified encryption key could not be found
400 InvalidImageStatus.NotValid The specified image status is not valid. The status of the specified image is unavailable and cannot be created.
400 InvalidImageVersion.NotSupported The specified image version is no longer supported. The specified image version is no longer supported. Please select another image.
400 InvalidMemberIp.DesktopAmount The desktop amount need to be 1. When you specify an IP to create a desktop, the number of desktops can only be 1
400 InvalidPolicyGroup.Status The target policy group is being created. Please try again later. The target policy group is being created. Try again later.
400 Protocol.NotAllowed Procotol of the image is not allowed. The protocol type of the image is not supported. Check the image ID.
400 ExistedHostname The specified hostname is existed on the domain. The specified hostname already exists in the current workspace
400 HostnameCannotCustomizeForLinux Customizing hostname is not supported for Linux desktop. The custom hostname feature does not support Linux desktops
400 IncorrectDirectoryStatus Only registered directory can create desktop. Workspace status error, only desktop creation with registered workspace is supported
400 IncorrectDirectoryType The protocol type of directory and desktop do not match. The protocol types of the specified workspace and the target desktop do not match, please check
400 InvalidAmount The specified Amount is not a valid value. The specified quantity is illegal
400 InvalidAmount.NotTimesOfUsers The specified Amount is notmatch EndUserId size. The number of desktops specified is not equal to the number of users to be assigned, please re-specify
400 InvalidDesktopBundle.NotFound The specified param BundleId is not found. Specified BundleId not found
400 InvalidDirectoryId.NotFound The specified param DirectoryId is not found. Unable to find workspace ID, please check workspace
400 InvalidDirectoryType.NotSupported The specified DirectoryType is not supported. Specified
400 InvalidEncryptionEnabled.Invalid The parameter VolumeEncryptionEnabled is invalid. When specifying the encryption key, you need to turn on the disk encryption function.
400 InvalidBundleId.NotFound The specified param BundleId is not found. The specified param BundleId is not found.
400 InvalidChargeType.Unsupported Input chargeType is invalid for the operation, please check. Input chargeType is invalid for the operation, please check.
400 InvalidImage.NotFound The specified image is not found. The specified image is not found.
400 InvalidOfficeSiteId The specified param OfficeSiteId is invalid. The specified param OfficeSiteId is invalid.
400 InvalidParam.NotSupportForMonthDesktop MonthDesktop bundle not support in this region. MonthDesktop bundle not support in this region.
400 InvalidParameter.Period The specified parameter Period is invalid. The specified parameter Period is invalid.
400 InvalidUserDiskSize.NotSupported The specified userDiskSize is invalid. The specified userDiskSize is invalid.
400 SubnetParamInvalid.SubnetId The specified parameter subnetId not exist or not valid. The specified parameter subnetId not exist or not valid.
400 SubnetParamInvalid.SubnetIpSize The specified parameter subnetId not exist or ip not enough. The specified parameter subnetId not exist or ip not enough.
400 INSUFFICIENT_QUOTA Insufficient quota. The user quota is insufficient.
400 NoStock The requested resource is sold out in the specified zone, try other types of resources or other regions and zones. The requested resource is sold out in the specified zone; try other types of resources or other regions and zones.
400 InvalidSPInstanceType.NotSupported Cannot find available instance type to SUPPORT SPECIFIC IMAGE feature. Cannot find available instance type to support [SUPPORT_SPECIFIC_IMAGE] feature.
400 InvalidParam The input param is not invalid, please check. The input param is not invalid, please check.
400 InvalidMemberIp.Allocated The specified ip has been allocated. The specified ip has been allocated
403 CREATE_SLR_ERROR You are not authorized to do this action. You are not authorized to do this action. Resource: acs:ram:*:*:role/* Action: ram:CreateServiceLinkedRole

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.