All Products
Search

This Product

    Elastic Desktop Service:CreateDesktopGroup

    Document Center

    Elastic Desktop Service:CreateDesktopGroup

    Last Updated:Jun 11, 2026

    Creating a shared EDS.

    Operation description

    • To learn more about shared cloud computers, including their features, use cases, limitations, and scaling policies, see shared cloud computer (formerly desktop group) overview.

    • Before calling this API, ensure you have created the necessary resources, such as an office network, a desktop template, and a policy.

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

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The ID of the region. To find the regions supported by Elastic Desktop Service (EDS), call the DescribeRegions operation.

    cn-hangzhou
    BundleId

    string

    No

    The bundle ID.

    b-je9hani001wfn****
    OfficeSiteId

    string

    Yes

    The ID of the office network for the desktops.

    cn-hangzhou+os-c5cy7q578s8jc****
    PolicyGroupId

    string

    Yes

    The ID of the policy to apply to the desktops.

    pg-9c2d6t2dwflqr****
    DesktopGroupName

    string

    No

    The name of the computer pool. The name must be 1 to 30 characters long, start with a letter or a Chinese character, and must not begin with http:// or https://. The name can contain Chinese characters, letters, digits, colons (:), underscores (_), periods (.), or hyphens (-).

    SharedComputers01
    DirectoryId

    string

    No

    The directory ID.

    Note

    This parameter is not yet available.

    dri-uf62w3qzt4aigvlcb****
    ScaleStrategyId

    string

    No

    The ID of the scaling policy.

    Note

    This parameter is not yet available.

    ss-f9dkjz6vw3aaw****
    VpcId

    string

    No

    The ID of the Virtual Private Cloud (VPC) that contains the office network for the desktops.

    Note

    This parameter is not yet available.

    vpc-uf6w8u60n8xbkg5el****
    DefaultInitDesktopCount

    integer

    No

    The default number of desktops to create in the computer pool. The default value is 1.

    1
    KeepDuration

    integer

    No

    The duration for which a session is kept active after a user disconnects. Unit: milliseconds. Valid values: 180000 (3 minutes) to 345600000 (4 days). A value of 0 indicates that the session is retained indefinitely.

    If a user reconnects within this period, they can resume their session. If they fail to reconnect, the session is terminated, and any unsaved data is lost.

    180000
    ChargeType

    string

    Yes

    The billing method of the desktops.

    Valid values:

    • PostPaid :

      pay-as-you-go

    • PrePaid :

      subscription

    PrePaid
    Period

    integer

    No

    The subscription duration for the desktops. This parameter is required only if ChargeType is set to PrePaid. The PeriodUnit parameter specifies the time unit for this duration.

    • If PeriodUnit is Month, the valid values are:

      • 1

      • 2

      • 3

      • 6

    • If PeriodUnit is Year, the valid values are:

      • 1

      • 2

      • 3

      • 4

      • 5

    1
    PeriodUnit

    string

    No

    The time unit of the subscription period.

    Valid values:

    • Month :

      Month

    • Year :

      Year

    Month
    OwnType

    integer

    No

    The type of the desktop.

    Note

    This parameter is not yet available.

    Valid values:

    • 0 :

      Personal (single-session)

    • 1 :

      Shared (multi-session)

    0
    AutoPay

    boolean

    No

    Specifies whether to automatically pay for subscription orders.

    true
    Comments

    string

    No

    A description or comments for the computer pool.

    comment
    MinDesktopsCount

    integer

    No

    The minimum number of desktops in the subscription computer pool. This parameter is required only if ChargeType is PrePaid. Valid values: 0 to MaxDesktopsCount. Default value: 1.

    1
    MaxDesktopsCount

    integer

    No

    The maximum number of desktops in the pay-as-you-go computer pool. Valid values: 0 to 500.

    50
    AllowAutoSetup

    integer

    No

    Specifies whether to allow automatic creation of desktops in the subscription computer pool. This parameter is required and applies only when ChargeType is set to PrePaid.

    Valid values:

    • 0 :

      Disallow

    • 1 :

      Allow

    1
    AllowBufferCount

    integer

    No

    The number of desktops to reserve in the pay-as-you-go computer pool. This parameter is required and applies only when ChargeType is set to PostPaid. Valid values:

    • 0: Does not reserve desktops.

    • N: Reserves N desktops, where N is an integer from 1 to 100.

    Note

    If no desktops are reserved, a user must wait for a new desktop to be created and started, which can cause connection delays. We recommend reserving an appropriate number of desktops to improve connection times.

    1
    ClientToken

    string

    No

    A client token to ensure the idempotence of the request. You can use your client to generate a token, but you must make sure that the token is unique among different requests. The token can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.

    123e4567-e89b-12d3-a456-426655440000
    EndUserIds

    array

    No

    An array of user IDs to authorize for the computer pool.

    string

    No

    A user ID.

    alice
    ResetType

    integer

    No

    The desktop reset type.

    Valid values:

    • 0 :

      Do not reset.

    • 1 :

      Reset only the system disk.

    • 2 :

      Reset only the user disk.

    • 3 :

      Reset both the system and user disks.

    0
    LoadPolicy

    integer

    No

    The load balancing policy for the multi-session computer pool.

    Note

    This parameter is not yet available.

    Valid values:

    • 0 :

      Depth-first

    • 1 :

      Breadth-first

    0
    BindAmount

    integer

    No

    The number of concurrent sessions allowed per desktop in a multi-session computer pool.

    Note

    This parameter is not yet available.

    2
    Classify

    string

    No

    The type of the computer pool.

    Note

    This parameter is not yet available.

    Valid values:

    • teacher :

      Desktop for teachers

    • student :

      Desktop for students

    teacher
    AllClassifyUsers

    boolean

    No

    Specifies whether to authorize all users in the computer pool's categories.

    Note

    This parameter is not yet available.

    Alice
    VolumeEncryptionEnabled

    boolean

    No

    Specifies whether to enable disk encryption.

    false
    VolumeEncryptionKey

    string

    No

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

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

    number

    No

    The session usage threshold that triggers auto scaling for multi-session computer pools. Session usage is calculated by using the following formula:

    Session usage = (Number of connected sessions / (Total number of desktops × Maximum number of sessions per desktop)) × 100%

    When session usage reaches this threshold, new desktops are created. When session usage falls below this threshold, the group scales in by deleting surplus desktops.

    Note

    This parameter is not yet available.

    0.5
    ConnectDuration

    integer

    No

    The maximum duration of a connected session. When the session duration reaches this value, the session is automatically disconnected. Unit: milliseconds. Valid values: 900000 (15 minutes) to 345600000 (4 days).

    900000
    IdleDisconnectDuration

    integer

    No

    The maximum duration that a session can be idle before it is automatically disconnected. A session is considered idle if there is no keyboard or mouse input. Unit: milliseconds. Valid values: 360000 (6 minutes) to 3600000 (60 minutes).

    Thirty seconds before disconnection, the user is prompted to save their work to prevent data loss.

    Note

    This parameter applies only to desktops created from image version 1.0.2 or later.

    360000
    StopDuration

    integer

    No

    The amount of time a desktop can be idle before it is automatically stopped. Connecting to a stopped desktop automatically starts it. Unit: milliseconds.

    300000
    ProfileFollowSwitch

    boolean

    No

    Specifies whether to enable user data roaming.

    Note

    This parameter is not yet available.

    false
    FileSystemId

    string

    No

    The ID of the Apsara File Storage NAS file system used for user data roaming.

    Note

    This parameter is not yet available.

    kegd-nas-****
    BuyDesktopsCount

    integer

    No

    • For subscription computer pools: The number of desktops to purchase. Valid values: 0 to 200.

    • For pay-as-you-go computer pools: The minimum number of desktops in the group. Valid values: 0 to MaxDesktopsCount. The default value is 1.

    3
    GroupVersion

    integer

    No

    The version of the computer pool.

    2
    AutoRenew

    boolean

    No

    Specifies whether to enable auto-renewal for the subscription computer pool.

    Valid values:

    • true :

      Enables auto-renewal.

    • false :

      Disables auto-renewal.

    false
    Tag

    array<object>

    No

    The list of tags. You can specify up to 20 tags.

    object

    No

    A tag.

    Key

    string

    Yes

    The tag key. The key cannot be an empty string, can be up to 128 characters long, and cannot start with aliyun or acs:. It cannot contain http:// or https://.

    TestKey
    Value

    string

    Yes

    The value of the tag. The value can be an empty string. The value can be up to 128 characters in length and cannot start with acs:. It cannot contain http:// or https://.

    TestValue
    PromotionId

    string

    No

    The promotion ID.

    youhuiquan_promotion_option_id_*****
    ImageId

    string

    No

    The image ID.

    m-gx2x1dhsmusr2****
    SystemDiskCategory

    string

    No

    The type of the system disk.

    Valid values:

    • cloud_auto :

      ESSD AutoPL cloud disk

    • cloud_essd :

      Enhanced SSD (ESSD)

    cloud_auto
    SystemDiskSize

    integer

    No

    The size of the system disk. Unit: GiB.

    Note

    The system disk size must be at least the size of the image.

    80
    SystemDiskPerLevel

    string

    No

    The performance level (PL) of the ESSD. Default value: PL0.

    Valid values:

    • PL1 :

      PL1

    • PL0 :

      PL0

    PL0
    DataDiskCategory

    string

    No

    The type of the data disk.

    Valid values:

    • cloud_auto :

      ESSD AutoPL cloud disk

    • cloud_essd :

      Enhanced SSD (ESSD)

    cloud_auto
    DataDiskSize

    integer

    No

    The size of the data disk. Unit: GiB. The value must be a multiple of 20 and in the range of 0 to 16,380.

    • A value of 0 indicates that no data disk is attached.

    • If the selected bundle uses an SSD, the minimum data disk size is 20 GiB.

    Default value: 0

    80
    DataDiskPerLevel

    string

    No

    The performance level (PL) of the ESSD. Default value: PL0.

    Valid values:

    • PL1 :

      PL1

    • PL0 :

      PL0

    PL0
    DefaultLanguage

    string

    No

    The system language.

    Valid values:

    • en-US :

      English

    • zh-HK :

      Traditional Chinese

    • zh-CN :

      Simplified Chinese

    • ja-JP :

      Japanese

    zh-CN
    DesktopType

    string

    No

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

    eds.enterprise_office.16c64g
    Hostname

    string

    No

    The custom hostname for the desktops. This parameter is applicable only to Windows desktops in an AD office network.

    The hostname must meet the following naming conventions:

    • Must be 2 to 15 characters in length.

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

    To generate sequential hostnames when creating multiple desktops, use the format name_prefix[begin_number,bits]name_suffix. For example, if you set the Hostname parameter to ecd-[1,4]-test, the first desktop is named ecd-0001-test, the second is named 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, which can be an integer from 0 to 999999. The default value is 0. bits is the number of digits, which can be an integer from 1 to 6. The default value is 6.

    • name_suffix: The suffix of the hostname.

    testhost
    MultiResource

    boolean

    No

    Specifies whether to create a computer pool.

    Valid values:

    • true :

      Create a computer pool.

    • false :

      Create one or more individual desktops.

    false
    ExclusiveType

    string

    No

    Specifies the pool type. To create a static pool, set this parameter to Exclusive. This is required if SessionType is MultipleSession.

    Exclusive
    GroupAmount

    integer

    No

    The number of individual desktops to create. This parameter is required only if MultiResource is set to false. Valid values: 1 to 5. Default value: 1.

    1
    SessionType

    string

    No

    The session type.

    Valid values:

    • SingleSession :

      Single-session

    • MultipleSession :

      Multi-session

    SingleSession
    TimerGroupId

    string

    No

    The ID of the scheduled task group.

    ccg-0caoeogrk9m5****
    SnapshotPolicyId

    string

    No

    The ID of the automatic snapshot policy.

    sp-28mp6my0l6zow****
    ResellerOwnerUid

    integer

    No

    UserOuPath

    string

    No

    UserGroupName

    string

    No

    SimpleUserGroupId

    string

    No

    DeleteDuration

    integer

    No

    Response elements

    Element

    Type

    Description

    Example

    object

    The response data.

    DesktopGroupId

    string

    The ID of the computer pool.

    dg-2i8qxpv6t1a03****
    RequestId

    string

    The request ID.

    3EB7FCEE-D731-4948-85A3-4B2C341CA983
    OrderIds

    array

    The order IDs.

    string

    An order ID. Returned only when ChargeType is set to PrePaid.

    123456789
    DesktopGroupIds

    array

    The computer pool IDs.

    string

    A computer pool ID.

    ['dg-1np2yupx0uim****']

    Examples

    Success response

    JSON format

    {
  "DesktopGroupId": "dg-2i8qxpv6t1a03****",
  "RequestId": "3EB7FCEE-D731-4948-85A3-4B2C341CA983",
  "OrderIds": [
    "123456789"
  ],
  "DesktopGroupIds": [
    "['dg-1np2yupx0uim****']"
  ]
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.