Help Center/ Workspace/ API Reference/ Workspace APIs/ Order/ Creating a Desktop Order
Updated on 2025-07-14 GMT+08:00

Creating a Desktop Order

Function

Creates a desktop order.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /v2/{project_id}/desktops/orders/subscribe

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

User token.

It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

enterprise_project_id

No

String

Enterprise project ID, which is 0 by default.

hour_package_resources

Yes

Array of HourPackageResource objects

Hourly package resource.

extend_param

No

OrderExtendParam object

Extended parameter of the order.

Table 4 HourPackageResource

Parameter

Mandatory

Type

Description

period_type

No

Integer

Subscription period type. The value can be 2 (monthly) or 3 (yearly). This parameter is mandatory.

period_num

No

Integer

Number of subscription periods.

is_auto_renew

No

Integer

Whether auto-renewal is enabled.

used_up_policy

No

String

Duration exhaustion policy:

  • SHUTDOWN_OR_HIBERNATE: automatic shutdown or hibernation

  • PAY_PER_USE: automatic pay-per-use billing

create_desktops

No

CreateDesktopReq object

Request for creating a desktop.

Table 5 CreateDesktopReq

Parameter

Mandatory

Type

Description

desktop_type

Yes

String

Specifies the cloud desktop type.

  • DEDICATED: dedicated desktop for a single user.

  • SHARED: Multiple users share the desktop.

availability_zone

No

String

AZ. Creates a desktop in the specified AZ. If this parameter is not specified, the default AZ is used.

product_id

Yes

String

Package ID.

image_type

Yes

String

Image type. The default value is private.

  • private: a private image

  • gold: a public image

image_id

Yes

String

Image ID. This parameter is used together with product_id for creating desktops using custom images.

root_volume

Yes

Volume object

System disk.

data_volumes

No

Array of Volume objects

Data disks.

nics

No

Array of Nic objects

Information about the NIC corresponding to the desktop. If this parameter is not specified, the default NIC is used.

security_groups

No

Array of SecurityGroup objects

Security group used by the desktop. If no security group is specified, the security group specified in the desktop agent is used by default.

desktops

No

Array of Desktop objects

Parameters used for creating a desktop. The value contains 1 to 50 characters.

Currently, a batch of desktops cannot have different configurations. The configurations of all desktops must be the same as those of the first desktop. If no parameter is specified for the first desktop, the outer parameters with the same name are used.

desktop_name

No

String

This parameter is used together with size. If size is set to 1, this parameter indicates the desktop name, which consists of 1 to 15 characters. If size is set to a value greater than 1, this parameter indicates the desktop name prefix, which consists of 1 to 13 characters.

desktop_ips

No

Array of strings

IP addresses assigned to the desktop. The value ranges from 0 to 100.

size

No

Integer

Number of desktops that are not assigned to users. This parameter cannot be used together with desktops. It is used together with desktop_name.

email_notification

No

Boolean

Whether to send an email to notify the desktop user after a desktop is created. The default value is true.

enterprise_project_id

No

String

Enterprise project ID, which is 0 by default.

tags

No

Array of Tag objects

Tags.

apply_shared_vpc_dedicated_param

No

ApplySharedVpcDedicatedParam object

Input parameter of the shared VPC Direct Connect.

eip

No

Eip object

EIP information.

desktop_name_policy_id

No

String

Policy ID, which is used to specify the desktop name generation policy. If a desktop name is specified, the specified desktop name is used preferentially.

hour_package_product_id

No

String

Hourly desktop package ID.

hour_package_offering_id

No

String

Offering ID of an hourly desktop package.

Table 6 Volume

Parameter

Mandatory

Type

Description

type

Yes

String

Desktop data disk type, which must be the same as the disk type provided by the system.

  • SAS: high I/O

  • SSD: ultra-high I/O

  • GPSSD: general-purpose SSD

size

Yes

Integer

Disk capacity in GB. The system disk size ranges from 80 to 32760, and the data disk size ranges from 10 to 32760. The value must be a multiple of 10.

Table 7 Nic

Parameter

Mandatory

Type

Description

subnet_id

Yes

String

ID of the subnet on which the NIC works.

Table 8 SecurityGroup

Parameter

Mandatory

Type

Description

id

Yes

String

Security group ID.

Table 9 Desktop

Parameter

Mandatory

Type

Description

user_name

Yes

String

User to whom a desktop belongs. After a desktop is created, the user can log in to the desktop. Only letters, digits, hyphens (-), and underscores (_) are allowed. When the domain type is LITE_AD, the value contains 1 to 20 characters starting with a letter. When the domain type is LOCAL_AD, the value contains 1 to 32 characters starting with a letter or digit. A Windows desktop username can contain a maximum of 20 characters, and a Linux desktop username can contain a maximum of 32 characters.

user_email

No

String

Valid user email. After a desktop is created, the system informs users through emails.

user_phone

No

String

Mobile number of a valid user.

user_group

No

String

User group to which the desktop user belongs.

  • sudo: Linux administrator group.

  • default: Default Linux user group.

  • administrators: Windows administrator group. Administrators have full access to the desktop and can make any required changes except for forbidden operations.

  • users: standard Windows user group. Standard users can use most software programs and change system settings that do not affect other users.

computer_name

No

String

Desktop name, which must be unique. The desktop name can contain 1 to 15 characters in letters, digits, and hyphens (-). It must start with a letter or digit and cannot end with a hyphen (-).

os_host_name

No

String

Computer name in the OS.

desktop_name_prefix

No

String

Desktop name prefix. This parameter takes effect when computer_name is not specified.

Table 10 Tag

Parameter

Mandatory

Type

Description

key

Yes

String

Specifies the tag key. This parameter cannot be left blank and can contain a maximum of 128 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,|/.

value

No

String

Value of a tag, which can contain a maximum of 43 Unicode characters. The value can contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_). The value cannot contain the following characters: =*<>,|/.

Table 11 ApplySharedVpcDedicatedParam

Parameter

Mandatory

Type

Description

address

No

String

Shared VPC Direct Connect address specified by the tenant.

port

No

Integer

Shared VPC Direct Connect address port specified by the tenant.

availability_zone

No

Array of strings

AZ used for subscribing to service resources. By default, two AZs are randomly used.

Table 12 Eip

Parameter

Mandatory

Type

Description

id

No

String

ID of the EIP bound to the desktop. If this parameter is specified, the EIP is preferentially bound.

type

No

String

EIP type. The value can be 5_bgp (dynamic BGP) or 5_sbgp (static BGP).

charge_mode

No

String

EIP bandwidth billing mode.

  • TRAFFIC: billed by traffic.

  • BANDWIDTH: billed by bandwidth.

bandwidth_size

No

Integer

Bandwidth size.

Table 13 OrderExtendParam

Parameter

Mandatory

Type

Description

is_auto_pay

No

String

Whether to automatically pay. true: yes; false (default value): no

Response Parameters

Status code: 200

Table 14 Response body parameters

Parameter

Type

Description

order_id

String

Order ID, which is returned when an order is successfully placed.

Status code: 400

Table 15 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error description.

error_detail

String

Error details.

encoded_authorization_message

String

Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 409

Table 16 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error description.

error_detail

String

Error details.

encoded_authorization_message

String

Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Status code: 500

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code, which is returned upon failure.

error_msg

String

Error description.

error_detail

String

Error details.

encoded_authorization_message

String

Encrypted detailed reason for rejection. You can call the API decode-authorization-message of STS to decrypt the reason.

Example Requests

{
  "enterprise_project_id" : "0",
  "hour_package_resources" : [ {
    "period_type" : 2,
    "period_num" : 1,
    "is_auto_renew" : 0,
    "create_desktops" : {
      "desktop_type" : "DEDICATED",
      "email_notification" : true,
      "nics" : [ {
        "subnet_id" : "624afebf-bb07-4b20-89b1-e0a02f1137cd"
      } ],
      "tenantId" : "60ec8cdfb5974ddb8f75ba30952d52eb",
      "product_id" : "workspace.x86.flexus.xlarge2",
      "enterprise_project_id" : "0",
      "image_type" : "market",
      "image_id" : "4e8aebc3-f4dc-4789-a785-0a1769d44c0d",
      "root_volume" : {
        "type" : "SAS",
        "size" : 80
      },
      "data_volumes" : [ {
        "type" : "SAS",
        "size" : 10
      } ],
      "desktops" : [ {
        "user_name" : "hzh",
        "user_group" : "administrators"
      } ],
      "hour_package_product_id" : "workspace.x86.flexus.xlarge2.120hours"
    },
    "used_up_policy" : "SHUTDOWN_OR_HIBERNATE"
  } ]
}

Example Responses

Status code: 200

Response body for placing an order.

{
  "order_id" : "string"
}

Status Codes

Status Code

Description

200

Response body for placing an order.

400

The request cannot be understood by the server due to malformed syntax.

409

Operation conflict.

500

Internal server error.

Error Codes

See Error Codes.