• Workspace

workspace
  1. Help Center
  2. Workspace
  3. API Reference
  4. Desktops
  5. Creating Desktops

Creating Desktops

Function

This interface is used to create and assign desktops to users. After a desktop is created, users can log in to it. If this asynchronous interface is successfully invoked, the Workspace background receives the application request. If you want to check whether the desktop is successfully created, query the task execution status using the asynchronous job query interface. For details, see Asynchronous Job Query.

URI

  • URI format

    POST /v1.0/{project_id}/desktops

  • URI parameter description

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    string

    Specifies the user ID.

Request

  • Request body parameter description

    Parameter

    Mandatory

    Type

    Description

    desktops

    Yes

    List data structure [1]

    Specifies the list of parameters used for creating desktops. The current desktops only support one record. Calling an interface once only creates one desktop.

    email_notification

    No

    boolean

    Specifies whether to send an email to notify the desktop user after a desktop is created. The default value is true. This parameter is valid only when domain_type is set to LOCAL_AD during Workspace application. If domain_type is LITE_AD, it is invalid because an email must be sent to notify the desktop user of changing the login password when the desktop is created for the first time. Possible values are:

    • true: specifies that the system sends an email to the desktop user.
    • false: specifies that the system does not send an email to the desktop user.

    tags

    No

    List data structure [7]

    Specifies the desktop tag information.

[1] desktops field data structure description

Name

Mandatory

Type

Description

user_name

Yes

string

Specifies the workspace users. After a desktop is created, users can log in to it. The username can contain only letters, digits, hyphens (-), and underscores (_). When the domain type is LITE_AD, the username must start with a lowercase or uppercase letter and can contain 1 to 20 characters. When the domain type is LOCAL_AD, the username can start with a lowercase or uppercase letter or a digit and can contain 1 to 20 characters.

user_email

Yes

string

Specifies the valid email address. The system sends a notification email to the email address after the requested desktop is created.

product_id

Yes

string

Specifies the product package ID.

For the package information, see Querying the Product List.

image_id

No

string

Specifies the image ID. This parameter applies to scenarios where private images are used to create desktops and works with product_id.

root_volume

Yes

Dictionary data structure [3]

Specifies the system disk configuration of the desktop.

data_volumes

No

List data structure [4]

Specifies the data disk configuration of the desktop.

computer_name

Yes

string

Specifies the computer name, which can be viewed on the OS information page. The computer name must be unique.

The computer name must contain 1 to 15 characters and can contain only letters, digits, hyphens (-), and underscores (_). It must start with a letter.

user_group

No

string

Specifies the group to which a desktop user belongs.

ADMINISTRATORS: administrator group. Administrators have complete access to the desktop and can make any desired changes except for forbidden operations.

USERS: user group. Users in this group can use most software and change system settings that do not affect other users.

security_groups

No

List data structure [2]

Specifies the security group used by the desktop. If this is not available, use the specified security group in the desktop proxy by default.

nics

No

List data structure [5]

Specifies the NICs corresponding to the desktop. If this is not specified, the default NIC is used.

availability_zone

No

string

Specifies the availability zone. Desktops are created in the specified availability zone. If it is not specified, a ramdom availability zone is used. Information about availability zones can be obtained from Regions and Endpoints.

os:scheduler_hints

No

List data structure [6]

Specifies the desktop scheduling information.

license_type

No

string

Specifies the OS license type. The default type is system. This parameter is used to specify the license type used by the desktop OS. Possible values are:

  • system: uses the license provided by the service. The OS is automatically activated after desktop creation.
  • byol: uses your own valid license. You need to manually activate the OS after desktop creation.
    NOTE:
    • If you want to use the license of the byol type, you must create the desktop on a dedicated host. Otherwise, only the license of the system type can be used.
    • If a private image is used and the image OS is Windows 7 or Windows 10, you must use the license of the byol type.

ou_name

No

string

The parameter is valid only when domain_type is set to LOCAL_AD. You do not need to set it when domain_type is set to LITE_AD. Enter a maximum of 5 levels and levels from each other using a slash (/). Only letters, digits, spaces (not before or after a slash), and special characters including -_/$!@&*?. are allowed, for example, ab/cd/ef.

[2] security_groups field data structure description

Name

Mandatory

Type

Description

id

Yes

string

Specifies the security group ID used by the desktop.

[3] root_volume field data structure description

Name

Mandatory

Type

Description

type

Yes

string

Specifies the system disk type of the desktop. The disk type must match the one provided by the system.

SATA: SATA disk

SSD: SSD disk

size

Yes

integer

Specifies the system disk size (GB). The value ranges from 80 to 32768 and must be greater than or equal to the minimum size of the system disk in the image, that is, the value of the min_disk attribute.

[4] data_volumes field data structure description

Name

Mandatory

Type

Description

type

Yes

string

Specifies the data disk type of the desktop. The disk type must match the one provided by the system.

SATA: SATA disk

SSD: SSD disk

size

Yes

integer

Specifies the data disk space (GB). The value ranges from 10 to 32768.

[5] nics field data structure description

Name

Mandatory

Type

Description

subnet_id

Yes

string

Specifies the subnet ID corresponding to the NIC. If this field is specified, the subnet_id is mandatory.

ip_address

No

string

Specifies the IP address, which is automatically assigned if this field is blank or a null string.

[6] os:scheduler_hints field data structure description

Name

Mandatory

Type

Description

tenancy

No

string

Creates desktops on a dedicated or shared host. Possible values are:

shared: uses the shared host (default value).

dedicated: uses the dedicated host.

dedicated_host_id

No

string

Specifies the desktop dedicated host ID.

If the desktop dedicated host ID is specified, the desktop is placed on the dedicated host.

If the desktop dedicated host ID is not specified, the desktop is automatically placed on an available dedicated host.

Note:

  • This field takes effect only when tenancy is set to dedicated.
  • If the desktop is to be automatically created and placed, you need to enable the automatic placement function of the desktop dedicated host.

[6] tags field data structure description

Name

Mandatory

Type

Description

key

Yes

string

Specifies the key of a tag that cannot be empty and can contain a maximum of 36 unicode characters. The characters of a tag value may contain uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_).

value

No

string

Specifies the value of the tag that has a maximum length of 43 unicode characters, including uppercase and lowercase letters, digits, hyphens (-), and underscores (_).

  • Request example

    When the domain type is LITE_AD:

    POST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops
    Request Body:
    {
        "desktops": [{
            "user_name": "test",
            "user_group": "USERS",
            "user_email": "test@test.com",
            "product_id": "workspace.s.large.windows",
            "image_id": "66b9760c-02f0-4e3f-9946-4315cf299dc5",
            "computer_name": "test",
            "security_groups": [{
                "id": "631e70c6-c788-4522-8a26-9ef0f98c546a"
            }],
            "root_volume": {
                "type": "SATA",
                "size": 80
            },
            "data_volumes": [{
                "type": "SATA",
                "size": 100
            }],
            "nics": [{
                "subnet_id": "c962adaa-55b2-42ef-8e40-fd812221a96d"
            },
            {
                "subnet_id": "ebb535f7-5730-496c-b26a-601ddfffd2fe",
                "ip_address": "192.168.0.65"
            }],
            "availability_zone": "az01",
            "os:scheduler_hints": {             "tenancy": "dedicated",             "dedicated_host_id": "d6a3fcb5-8f1c-4bb8-86b1-997e5dccdefb"         },         "license_type": "system"
        }], 
        "tags": [{ 
                 "key": "key1",
                "value": "value1"
             }, 
             { 
                 "key": "key2", 
                 "value": "value2" 
         }]
    }

    When the domain type is LOCAL_AD:

    POST /v1.0/29dfe82ada564ac2b927e1ff036d9a9b/desktops
    Request Body: 
    { 
        "desktops": [{ 
            "user_name": "test", 
            "user_group": "USERS", 
            "user_email": "test@test.com", 
            "product_id": "workspace.s.large.windows", 
            "image_id": "66b9760c-02f0-4e3f-9946-4315cf299dc5", 
            "computer_name": "test", 
            "security_groups": [{ 
                "id": "631e70c6-c788-4522-8a26-9ef0f98c546a" 
            }], 
            "root_volume": { 
                "type": "SATA", 
                "size": 80 
            }, 
            "data_volumes": [{ 
                "type": "SATA", 
                "size": 100 
            }], 
            "nics": [{ 
                "subnet_id": "c962adaa-55b2-42ef-8e40-fd812221a96d" 
            }, 
            { 
                "subnet_id": "ebb535f7-5730-496c-b26a-601ddfffd2fe", 
                "ip_address": "192.168.0.65" 
            }], 
            "availability_zone": "az01", 
            "os:scheduler_hints": { 
                "tenancy": "dedicated", 
                "dedicated_host_id": "d6a3fcb5-8f1c-4bb8-86b1-997e5dccdefb" 
            }, 
            "license_type": "system",  
            "ou_name": "abc"
        }], 
        "email_notification": false,
        "tags": [{ 
                 "key": "key1",
                "value": "value1"
             }, 
             { 
                 "key": "key2", 
                 "value": "value2" 
         }]
    }

Response

  • Description

    Name

    Type

    Description

    job_id

    string

    Specifies the ID of a desktop creation job. Users can use this ID to query the execution status of jobs.

  • Response example
    {
       "job_id": "a25e3d3f-8a8e-4789-bd3f-a04e230640fd"
    }

Returned Values

  • Normal

    200

  • Abnormal

    Returned Value

    Description

    400 Bad Request

    The request syntax is incorrect and cannot be understood by the server.

    401 Unauthorized

    Authentication fails.

    403 Forbidden

    You are not authorized to perform the operation.

    404 Not Found

    The requested resource is not found.

    405 Method Not Allowed

    The method specified in the request is not allowed.

    500 Internal Server Error

    Internal service error. For details about error codes, see Error Code Description.

    503 Service Unavailable

    The service is unavailable.