DocsICP FilingConsole
官方文档
首页

CreateDesktops

更新时间：
复制 MD 格式
产品详情
我的收藏

Creates one or more cloud computers. You can also assign the cloud computers upon creation by providing user information.

Operation description

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

Examples

Example of creating a cloud desktop from a bundle

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office site 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 bundle

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office site 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 creating a cloud desktop with a monthly hour-based plan

{
  "RegionId": "cn-hangzhou",
  "DesktopName": "test-desktop-name",
  "Amount": "1",
  "OfficeSiteId": "cn-hangzhou+dir-xxx",// An office site 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 creating an agent

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

To automatically run a custom command script on a cloud desktop, use the UserCommands field.

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 obtain a list of regions supported by Elastic Desktop Service (EDS).

cn-hangzhou
GroupId

string

No

The ID of the desktop group.

dg-boyczi8enfyc5****
BundleId

string

No

The ID of the bundle. If this parameter is not specified, you must provide the parameters required to create the desktop.

b-je9hani001wfn****
DesktopName

string

No

The name of the desktop. The name must meet the following requirements:

  • The name cannot exceed 64 characters in length.

  • It must start with a letter or a Chinese character. It cannot start withhttp:// or https://.

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

DemoComputer01
UserName

string

No

Note

This parameter is not publicly available.

username
VpcId

string

No

Note

This parameter is not publicly available.

vpc-uf6w8u60n8xbkg5el****
Amount

integer

No

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

1
DirectoryId

string

No

Note

This parameter is not publicly available.

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

Valid values:

  • PostPaid :

    pay-as-you-go. (Default)

  • PrePaid :

    subscription.

PrePaid
Period

integer

No

The subscription duration. This parameter is required only when ChargeType is set to PrePaid. The unit of the duration is specified by PeriodUnit.

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

    • 1

    • 2

    • 3

    • 6

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

    • 1

    • 2

    • 3

    • 4

    • 5

1
PeriodUnit

string

No

The unit of the subscription duration.

Valid values:

  • Month :

    The unit is months. (Default)

  • Year :

    The unit is years.

Month
AutoPay

boolean

No

Specifies whether to enable automatic payment.

Valid values:

  • true :

    Enables automatic payment. Make sure that your account has a sufficient balance. Otherwise, an unpaid order is generated. (Default)

  • false :

    Generates an order but does not complete the payment. You can log on to the console, go to the **My Orders** page in the **User Center**, and complete the payment by using the returned order ID.

false
AutoRenew

boolean

No

Specifies whether to enable auto-renewal. This parameter is valid only when ChargeType is set to PrePaid.

Valid values:

  • true :

    Enables auto-renewal. The renewal duration is the same as the subscription duration.

  • false :

    Disables auto-renewal. (Default)

false
PromotionId

string

No

The ID of the promotion.

23141
UserAssignMode

string

No

The desktop assignment mode.

Note

If you do not specify the EndUserId parameter, the created desktops are not assigned to any end user.

Valid values:

  • ALL :

    Assigns the created desktops to each specified end user. (Default)

  • PER_USER :

    Evenly distributes the created desktops among the specified end users. In this case, the value of Amount must be divisible by the number of specified end users.

ALL
Hostname

string

No

The custom hostname of the desktop. This parameter is supported only for Windows-based desktops that are in an AD office network.

The hostname must meet the following requirements:

  • It must be 2 to 15 characters in length.

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

When you create multiple desktops, you can use the name_prefix[begin_number,bits]name_suffix format to name the desktops sequentially. For example, if you set the Hostname parameter to ecd-[1,4]-test, the resulting hostnames are ecd-0001-test, 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 start 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 IDs of end users to whom the desktops will be assigned. You can specify 1 to 100 end user IDs.

123456789

string

No

The ID of an end user to assign to a desktop.

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

  • If you do not specify the EndUserId parameter, the created desktops are not assigned to any end user.

alice
Tag

array<object>

No

The tags to add to the desktop. You can add up to 20 tags.

object

No

A tag.

Key

string

No

The key of the tag.

TestKey
Value

string

No

The value of the tag.

TestValue
DesktopNameSuffix

boolean

No

Specifies whether to automatically add a suffix to the desktop name when you create multiple desktops.

Valid values:

  • true :

    Automatically adds a suffix. (Default)

  • false :

    Does not add a suffix.

false
VolumeEncryptionEnabled

boolean

No

Specifies whether to enable disk encryption.

Valid values:

  • true :

    Enables disk encryption.

  • false :

    Disables disk encryption. (Default)

false
VolumeEncryptionKey

string

No

The ID of the Key Management Service (KMS) key to use for disk encryption. You can call the ListKeys operation to obtain available key IDs.

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

string

No

The private IP address of the desktop.

10.0.0.1
UserCommands

array<object>

No

A list of custom commands to run on the desktop after it is created.

object

No

A custom command.

ContentEncoding

string

No

The encoding method for the command content (Content).

Valid values:

  • Base64 :

    The content is Base64-encoded.

  • PlainText :

    The content is in plain text.

Base64
Content

string

No

The content of the command.

bmV3LWl0ZW0gZDpcdGVzdF91c2VyX2NvbW1hbmRzLnR4dCAtdHlwZSBm****
ContentType

string

No

The command type.

Valid values:

  • RunPowerShellScript :

    PowerShell commands for Windows instances.

  • RunShellScript :

    Shell commands for Linux instances.

  • RunBatScript :

    Batch commands for Windows instances.

RunPowerShellScript
BundleModels

array<object>

No

The list of bundles.

object

No

A bundle.

BundleId

string

No

The ID of the bundle.

b-je9hani001wfn****
Amount

integer

No

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

1
EndUserIds

array

No

The list of end users to whom the desktops are assigned.

string

No

The username.

alice
DesktopName

string

No

The name of the desktop. The name must meet the following requirements:

  • The name can be up to 64 characters long.

  • It must start with a letter or a Chinese character. It cannot start withhttp:// or https://.

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

DemoComputer02
Hostname

string

No

The custom hostname of the desktop. This parameter is supported only for Windows-based desktops that are in an AD office network.

The hostname must meet the following requirements:

  • It must be 2 to 15 characters in length.

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

When you create multiple desktops, you can use the name_prefix[begin_number,bits]name_suffix format to name the desktops sequentially. For example, if you set the Hostname parameter to ecd-[1,4]-test, the resulting hostnames are ecd-0001-test, 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 start 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 disk encryption.

false
VolumeEncryptionKey

string

No

The ID of the KMS key to use for disk encryption. You can call the ListKeys operation to obtain available key IDs.

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

array<object>

No

The details of scheduled tasks for the desktop. This parameter is being deprecated. We recommend that you use the TimerGroupId parameter instead.

object

No

The details of a scheduled task for the desktop.

TimerType

string

No

The type of the scheduled task.

NoOperationReboot
CronExpression

string

No

The cron expression for the scheduled task.

Important The time must be in UTC. For example, to specify 00:00 every day in the UTC+8 time zone, enter 0 0 16 ? * 1,2,3,4,5,6,7.

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

integer

No

The interval, in minutes.

10
Enforce

boolean

No

Specifies whether to forcibly execute the scheduled task.

Valid values:

  • true :

    Forcibly executes the scheduled task, regardless of the desktop connection status.

  • false :

    Does not forcibly execute the task.

true
ResetType

string

No

The reset type of the desktop.

Valid values:

  • RESET_TYPE_SYSTEM :

    Resets the system disk.

  • RESET_TYPE_BOTH :

    Resets both the system disk and the data disk.

RESET_TYPE_SYSTEM
OperationType

string

No

The operation to perform for the scheduled task. This parameter is supported only for disconnection-triggered tasks.

Valid values:

  • Hibernate :

    Hibernates the desktop.

  • Shutdown :

    Shuts down the desktop.

Shutdown
AllowClientSetting

boolean

No

Specifies whether to allow end users to configure scheduled tasks.

true
SubnetId

string

No

The ID of the subnet.

vsw-bp1m*****
MonthDesktopSetting

object

No

The settings for the monthly usage package.

UseDuration

integer

No

The number of hours included in the monthly usage package. Valid values: 120, 250, and 360.

null
BuyerId

integer

No

Note

This parameter is not publicly available.

null
DesktopId

string

No

Note

This parameter is not publicly available.

null
SnapshotPolicyId

string

No

The ID of the snapshot policy.

sp-28mp6my0l6zow****
ResourceGroupId

string

No

The ID of the resource group.

rg-3mtuc28rx95lx****
DesktopAttachment

object

No

The parameters for creating a desktop without a bundle. This parameter is ignored if you specify the BundleId parameter.

ImageId

string

No

The ID of the image.

m-39ddhdb0ggzjx*****
SystemDiskCategory

string

No

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

  • cloud_auto: SSD cloud disk

  • cloud_essd: ESSD

cloud_auto
SystemDiskSize

integer

No

The size of the system disk, in GiB. The value must be from 60 to 500, and must be a multiple of 10.

40
SystemDiskPerLevel

string

No

The performance level (PL) of the ESSD. This parameter is required if you set the disk type to ESSD. Valid values:

  • PL0

  • PL1

PL0
DataDiskSize

integer

No

The size of the data disk, in GiB. The value must be from 40 to 2040, and must be a multiple of 10.

40
DataDiskCategory

string

No

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

  • cloud_auto: SSD cloud disk

  • cloud_essd: ESSD

cloud_auto
DataDiskPerLevel

string

No

The PL of the ESSD. This parameter is required if you set the disk type to ESSD. Valid values:

  • PL0

  • PL1

PL0
DefaultLanguage

string

No

The display language. Valid values:

  • zh-CN

  • zh-HK

  • en-US

  • ja-JP

zh-CN
DesktopType

string

No

The desktop type. You can call the DescribeDesktopTypes operation to query the supported desktop types.

eds.enterprise_office.8c16g
TimerGroupId

string

No

The ID of the scheduled task group.

ccg-0caoeogrk9m5****
SavingPlanId

string

No

Note

This parameter is not publicly available.

spn-26c1b7bcrjcI****
ResellerOwnerUid

integer

No

If you are a reseller, specify the ID of the user who will own the resource. Otherwise, omit this parameter.

1828644634819902
ExtendInfo

string

No

Extended information in a JSON string. This parameter is available only to internal customers.

{}
AppRuleId

string

No

The ID of the application management policy.

bwr-245d4e0e6b7d42f5afa97eb3fbc7e488
QosRuleId

string

No

The ID of the Quality of Service (QoS) rule for public bandwidth throttling.

qos-52fqmg6kvyro7zu4l
ChannelCookie

string

No

Note

This parameter is not publicly available.

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

object

No

Additional parameters for specific purchase types.

MonthlyCredits

integer

No

The monthly credit package for agent resources. Valid values: 200, 1600, and 4000.

200

Response elements

Element

Type

Description

Example

object

The response body.

OrderId

string

The order ID.

Note

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

123456789
RequestId

string

The request ID.

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

array

An array of IDs for the created cloud desktops.

string

The cloud desktop ID.

["ecd-gx2x1dhsmucyy****"]

Examples

Success response

JSON format

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

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

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.