All Products
Search
Document Center

Elastic Desktop Service:CreateDesktops

Last Updated:Jul 30, 2024

Creates cloud computers. If you specify end users when you create cloud computers, the cloud computers are assigned to the end users after the cloud computers are created.

Operation description

Before you create cloud computers, complete the following preparations:

If you want the cloud computers to automatically execute a custom command script, you can use the UserCommands field to configure a custom command.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
ecd:CreateDesktopscreate
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
GroupIdstringNo

The ID of the cloud computer pool.

dg-boyczi8enfyc5****
BundleIdstringYes

The ID of the cloud computer template.

b-je9hani001wfn****
DesktopNamestringNo

The name of the cloud computer. The name must meet the following requirements:

  • The name must be 1 to 64 characters in length.
  • The name must start with a letter but cannot start with http:// or https://.
  • The name can only contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).
testDesktopName
UserNamestringNo
Note This parameter is not publicly available.
To be hidden.
VpcIdstringNo
Note This parameter is not publicly available.
To be hidden.
AmountintegerNo

The number of cloud computers that you want to create. Valid values: 1 to 300. Default value: 1.

1
DirectoryIdstringNo
Note This parameter is not publicly available.
To be hidden.
OfficeSiteIdstringYes

The office network ID.

cn-hangzhou+os-c5cy7q578s8jc****
PolicyGroupIdstringYes

The ID of the policy.

system-all-enabled-policy
ChargeTypestringNo

The billing method of the cloud computers.

Default value: PostPaid. Valid values:

  • Postpaid: pay-as-you-go

  • PrePaid: subscription

PrePaid
PeriodintegerNo

The subscription duration of the cloud desktop that you want to create. The unit is specified by the PeriodUnit parameter. This parameter takes effect and is required only when the ChargeType parameter is set to PrePaid.

  • Valid values if the PeriodUnit parameter is set to Month:

    • 1
    • 2
    • 3
    • 6
  • Valid values if the PeriodUnit parameter is set to Year:

    • 1
    • 2
    • 3
    • 4
    • 5
1
PeriodUnitstringNo

The unit of the subscription duration.

Month
AutoPaybooleanNo

Specifies whether to enable automatic payment.

false
AutoRenewbooleanNo

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

false
PromotionIdstringNo

The ID of the sales promotion.

23141
UserAssignModestringNo

How the cloud computers are assigned.

Note If you do not specify the EndUserId parameter, the cloud computers are not assigned to end users after the cloud computers are created.

Default value: ALL. Valid values:

  • ALL: If you specify the EndUserId parameter, the cloud computers are assigned to all specified end users after the cloud computers are created.

  • PER_USER: If you specify the EndUserId parameter, the cloud computers are evenly assigned to the specified end users after the cloud computers are created.

    In this case, you must make sure that the value of the Amount parameter can be divided by the N value of the EndUserId.N parameter that you specify.

ALL
HostnamestringNo

The custom hostnames of the cloud computers. This parameter is valid only if the office network is an AD office network and the operating system type of the cloud computers is Windows.

The hostnames must meet the following requirements:

  • The hostnames must be 2 to 15 characters in length.
  • The hostnames can contain only letters, digits, and hyphens (-). The hostnames cannot start or end with a hyphen (-), contain consecutive hyphens (-), or contain only digits.

When you create multiple cloud computers, you can use the name_prefix[begin_number,bits]name_suffix naming format to name the cloud computers. For example, if you set the value of the Hostname parameter to ecd-[1,4]-test, the hostname of the first cloud computer is ecd-0001-test, the hostname of the second cloud computer is ecd-0002-test, and so on.

  • name_prefix: the prefix of the hostname.
  • [begin_number,bits]: the sequential number in the hostname. The begin_number value is the starting digit. Valid values of begin_number: 0 to 999999. Default value: 0. The bits value is the number of digits. Valid values: 1 to 6. Default value: 6.
  • name_suffix: the suffix of the hostname.
testhost
EndUserIdarrayNo

The IDs of the end users to which you want to assign the cloud computers. You can specify 1 to 100 IDs.

stringNo

The ID of an end user to which you want to assign the cloud computer.

  • During a specific period of time, only one end user can use the cloud computer.
  • If you do not specify the EndUserId parameter, the cloud computers are not assigned to any end user after the cloud computers are created.
test1
Tagarray<object>No

The tags that you want to add to the cloud desktop.

objectNo

The tag that you want to add.

KeystringNo

The key of the tag. You can specify 1 to 20 keys for a tag.

TestKey
ValuestringNo

The value of the tag. You can specify 1 to 20 values for a tag.

TestValue
DesktopNameSuffixbooleanNo

Specifies whether to automatically add suffixes to the names of cloud computers when you create multiple cloud computers at the same time.

Default value: true. Valid values:

  • true

  • False

false
VolumeEncryptionEnabledbooleanNo

Specifies whether to enable disk encryption.

false
VolumeEncryptionKeystringNo

The ID of the Key Management Service (KMS) key that you want to use when disk encryption is enabled. You can call the ListKeys operation to obtain a list of KMS keys.

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

The private IP address of the cloud computer.

10.0.0.1
UserCommandsarray<object>No

Details about the custom command scripts.

objectNo

The custom command script of the user.

ContentEncodingstringNo

The encoding mode of the command content.

Valid values:

  • Base64: encodes the command content in Base64.

  • PlainText: does not encode the command content.

Base64
ContentstringNo

The command content.

bmV3LWl0ZW0gZDpcdGVzdF91c2VyX2NvbW1hbmRzLnR4dCAtdHlwZSBm****
ContentTypestringNo

The language type of the command.

Valid values:

  • RunPowerShellScript: PowerShell commands (applicable to Windows cloud computers).

  • RunShellScript: shell commands (applicable to Linux cloud computers).

  • RunBatScript: batch commands (applicable to Windows cloud computers).

RunPowerShellScript
BundleModelsarray<object>No

The cloud computer templates.

objectNo

The desktop template that you want to use.

BundleIdstringNo

The ID of a cloud computer template.

b-je9hani001wfn****
AmountintegerNo

The number of cloud computers that you want to create. Valid values: 1 to 300. Default value: null.

1
EndUserIdsarrayNo

The IDs of the end users to whom the cloud computer are assigned.

stringNo

The name of an end user.

Alice
DesktopNamestringNo

The name of the cloud computer. The name must meet the following requirements:

  • The name must be 1 to 64 characters in length.
  • The name must start with a letter but cannot start with http:// or https://.
  • The name can only contain letters, digits, colons (:), underscores (_), periods (.), and hyphens (-).
testDesktopName
HostnamestringNo

The custom hostnames of the cloud computers. This parameter is valid only if the office network is an AD office network and the operating system type of the cloud computers is Windows.

The hostnames must meet the following requirements:

  • The hostnames must be 2 to 15 characters in length.
  • The hostnames can contain only letters, digits, and hyphens (-). The hostnames cannot start or end with a hyphen (-), contain consecutive hyphens (-), or contain only digits.

When you create multiple cloud computers, you can use the name_prefix[begin_number,bits]name_suffix naming format to name the cloud computers. For example, if you set the value of the Hostname parameter to ecd-[1,4]-test, the hostname of the first cloud computer is ecd-0001-test, the hostname of the second cloud computer is ecd-0002-test, and so on.

  • name_prefix: the prefix of the hostname.
  • [begin_number,bits]: the sequential number in the hostname. The begin_number value is the starting digit. Valid values of begin_number: 0 to 999999. Default value: 0. The bits value is the number of digits. Valid values: 1 to 6. Default value: 6.
  • name_suffix: the suffix of the hostname.
testhost
VolumeEncryptionEnabledbooleanNo

Specifies whether to enable disk encryption.

false
VolumeEncryptionKeystringNo

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

08c33a6f-4e0a-4a1b-a3fa-7ddfa1d4****
DesktopTimersarray<object>No

The details of the scheduled task on cloud computers.

objectNo
TimerTypestringNo

The type of the scheduled task.

NoOperationReboot
CronExpressionstringNo

The cron expression for the scheduled task.

Note The time must be in UTC. For example, for 24:00 (UTC+8), you must set the value to 0 0 16 ? * 1,2,3,4,5,6,7
0 40 7 ? * 1,2,3,4,5,6,7
IntervalintegerNo

The interval at which cloud computers are created. Unit: minutes.

10
EnforcebooleanNo

Specifies whether to forcibly execute the scheduled task.

Valid values:

  • true: forcibly executes the scheduled task regardless of the status and connection of the cloud computers.

  • false: does not forcibly execute the scheduled task.

True
ResetTypestringNo

The reset type of the cloud computers.

Valid values:

  • RESET_TYPE_SYSTEM: resets the system disks.

  • RESET_TYPE_BOTH: resets the system disks and data disks.

RESET_TYPE_SYSTEM
OperationTypestringNo

The operations that scheduled tasks support. This parameter is valid only when TimerType is set to NoConnect.

Valid values:

  • Hibernate: hibernates the cloud computers.

  • Shutdown: stops the cloud computers.

Shutdown
AllowClientSettingbooleanNo

Specifies whether to allow the end user to configure the scheduled task.

true
MonthDesktopSettingobjectNo
Note This parameter is not publicly available.
UseDurationintegerNo
Note This parameter is not publicly available.
null
BuyerIdlongNo
Note This parameter is not publicly available.
null
DesktopIdstringNo
Note This parameter is not publicly available.
null

Response parameters

ParameterTypeDescriptionExample
object

Schema of response.

OrderIdstring

The ID of the order.

Note This parameter is returned only when you set the ChargeType parameter to PrePaid.
123456789
RequestIdstring

The ID of the request.

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

The IDs of the cloud computers that are created. If multiple cloud computers are created, multiple IDs are returned.

string

The ID of the cloud computer.

["ecd-gx2x1dhsmucyy****"]

Examples

Sample success responses

JSONformat

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

Error codes

HTTP status codeError codeError messageDescription
400InvalidEncryptionKey.MissingParameter VolumeEncryptionKey is missing.When the disk encryption function is enabled, the encryption key cannot be empty.
400InvalidEncryptionKey.NotAuthorizedEds service cannot access the given VolumeEncryptionKey.Unable to access unauthorized encryption keys
400InvalidEncryptionKey.NotFoundThe specified VolumeEncryptionKey is not found.The specified encryption key could not be found
400InvalidImageStatus.NotValidThe specified image status is not valid.The status of the specified image is unavailable and cannot be created.
400InvalidImageVersion.NotSupportedThe specified image version is no longer supported.The specified image version is no longer supported. Please select another image.
400InvalidMemberIp.DesktopAmountThe desktop amount need to be 1.When you specify an IP to create a desktop, the number of desktops can only be 1
400InvalidPolicyGroup.StatusThe target policy group is being created. Please try again later.-
400Protocol.NotAllowedProcotol of the image is not allowed.The protocol type of the image is not supported. Check the image ID.
400ExistedHostnameThe specified hostname is existed on the domain.The specified hostname already exists in the current workspace
400HostnameCannotCustomizeForLinuxCustomizing hostname is not supported for Linux desktop.The custom hostname feature does not support Linux desktops
400IncorrectDirectoryStatusOnly registered directory can create desktop.Workspace status error, only desktop creation with registered workspace is supported
400IncorrectDirectoryTypeThe 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
400InvalidAmountThe specified Amount is not a valid value.The specified quantity is illegal
400InvalidAmount.NotTimesOfUsersThe 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
400InvalidDesktopBundle.NotFoundThe specified param BundleId is not found.Specified BundleId not found
400InvalidDirectoryId.NotFoundThe specified param DirectoryId is not found.Unable to find workspace ID, please check workspace
400InvalidDirectoryType.NotSupportedThe specified DirectoryType is not supported.Specified
400InvalidEncryptionEnabled.InvalidThe parameter VolumeEncryptionEnabled is invalid.When specifying the encryption key, you need to turn on the disk encryption function.

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2024-07-22The Error code has changed. The request parameters of the API has changedView Change Details
2024-04-29The Error code has changed. The request parameters of the API has changedView Change Details
2023-11-21The Error code has changed. The request parameters of the API has changedView Change Details
2023-11-15The Error code has changedView Change Details
2023-11-15The Error code has changedView Change Details
2023-05-24The request parameters of the API has changedView Change Details
2023-05-24The request parameters of the API has changedView Change Details
2023-04-24The request parameters of the API has changedView Change Details
2023-03-14The request parameters of the API has changedView Change Details
2022-08-08The request parameters of the API has changedView Change Details