文档首页/ 云桌面 Workspace/ API参考/ 云应用API/ 服务器组管理/ 创建服务器组 - CreateServerGroup
更新时间：2026-02-10 GMT+08:00
查看PDF
分享

创建服务器组 - CreateServerGroup

功能介绍

创建服务器组。

  • 服务器组是一组相同配置的服务器集合，服务器组内的服务器使用同一镜像创建，配置相同，运行相同的应用程序。用户在打开云应用时，会根据调度规则选取组内的一台可用服务器进行连接。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    workspace:serverGroup:create

    Write

    serverGroup *

    -

    -
    • ims:images:list
    • vpc:ports:get
    • vpc:subnets:get

    -

    • g:RequestTag/<tag-key>

    • g:TagKeys

    • g:EnterpriseProjectId

URI

POST /v1/{project_id}/app-server-groups

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目唯一标识。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

用户Token。

通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。
表3 请求Body参数

参数

是否必选

参数类型

描述

name

是

String

服务器组名称，名称需满足如下规则:

  1. 由中文，英文大小写，数字，_-组成，不能有空格。

  2. 长度范围1~64个字符。

image_id

是

String

服务器组关联的镜像ID，用于创建对应组下的云服务器。

image_product_id

否

String

服务器组的镜像产品ID，当镜像为云市场镜像时，该字段必填。

image_type

是

String

镜像类型：

  • gold - 云市场镜像

  • public - 公共镜像

  • private - 私有镜像

  • shared - 共享镜像

  • other - 其他

os_type

是

String

系统类型，当前仅支持Windows。

  • Linux -

  • Windows -

  • Other -

description

否

String

服务器组描述。

route_policy

否

RoutePolicy object

路由策略。

product_id

是

String

产品ID。

说明：

  • 获取方式详见产品套餐管理ListProduct："GET /v1/{project_id}/product"。

flavor_id

否

String

规格ID。

vpc_id

是

String

虚拟私有云ID。

subnet_id

是

String

网卡对应的子网ID。

system_disk_type

是

String

磁盘类型，获取可用磁盘类型详见接口磁盘管理ListVolumeType。

  • ESSD - 极速型SSD

  • SSD - 超高IO

  • GPSSD - 通用型SSD

  • SAS - 高IO

  • SATA - 普通IO

system_disk_size

是

Integer

磁盘容量，单位GB。

ou_name

否

String

默认组织名称。

cluster_id

否

String

云服务器系统盘对应的存储池的ID。

availability_zone

否

String

可用分区。

说明：

  • 将服务创建到指定的可用分区，如果不指定则使用系统随机的可用分区。

  • 获取方式详见可用区管理ListAvailabilityZone："GET /v1/{project_id}/availability-zone"。

ip_virtual

否

IpVirtual object

虚拟IP功能选项。

is_vdi

否

Boolean

是否为vdi单会话模式。

app_type

否

String

服务器组应用类型：

  • SESSION_DESKTOP_APP - 会话桌面app

  • COMMON_APP - 普通app

extra_session_type

否

String

付费会话类型：

  • GPU - GPU规格会话。

  • CPU - 普通CPU规格会话。

extra_session_size

否

Integer

付费会话数，单位/个。

tags

否

Array of TmsTag objects

标签信息，最多包含20个key,不允许重复。

enterprise_project_id

否

String

企业项目ID,仅企业项目需配置(字段为空或者0表示使用默认default企业项目)。

primary_server_group_id

否

String

主服务器组id,绑定主服务器组，则创建的是备服务器。

server_group_status

否

Boolean

是否启用服务器组。
表4 RoutePolicy

参数

是否必选

参数类型

描述

max_session

否

Integer

单台服务器最大的连接会话数。

cpu_threshold

否

Integer

cpu使用率阈值，单位为%。

mem_threshold

否

Integer

内存使用率阈值，单位为%。
表5 IpVirtual

参数

是否必选

参数类型

描述

enable

是

Boolean

是否启用虚拟IP功能。

启用虚拟IP功能将占用额外的ip地址，注意合理规划网络ip数量。

约束：

  • 只支持windows镜像。

  • 只支持在创建服务器组时设置功能开关，不支持更新功能开关。

  • 只支持具备dhcp动态分配ip能力的网络。
表6 TmsTag

参数

是否必选

参数类型

描述

key

是

String

键。最大长度128个unicode字符。

  1. 可用 UTF-8 格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格，以及以下字符： _ . : = + - @。

  2. 两头不能有空白字符。

value

否

String

值。每个值最大长度255个unicode字符。

  1. 可用 UTF-8 格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格，以及以下字符： _ . : = + - @。

响应参数

状态码：200

表7 响应Body参数

参数

参数类型

描述

id

String

服务器组的唯一标识。

name

String

服务器组名称。

description

String

服务器组描述。

image_id

String

服务器组关联的镜像ID，用于创建对应组下的云服务器。

os_type

String

系统类型，当前仅支持Windows。

  • Linux -

  • Windows -

  • Other -

product_id

String

产品id。

subnet_id

String

网卡对应的子网ID。

system_disk_type

String

磁盘类型，获取可用磁盘类型详见接口磁盘管理ListVolumeType。

  • ESSD - 极速型SSD

  • SSD - 超高IO

  • GPSSD - 通用型SSD

  • SAS - 高IO

  • SATA - 普通IO

system_disk_size

Integer

磁盘容量，单位GB。

is_vdi

Boolean

是否为vdi单会话模式。

extra_session_type

String

付费会话类型：

  • GPU - GPU规格会话。

  • CPU - 普通CPU规格会话。

extra_session_size

Integer

付费会话个数。

app_type

String

服务器组应用类型：

  • SESSION_DESKTOP_APP - 会话桌面app

  • COMMON_APP - 普通app

create_time

String

服务器组创建时间。

update_time

String

服务器组更新时间。

storage_mount_policy

String

用户访问APS的应用时，对应NAS存储目录在APS上的挂载策略。

  • USER - 仅挂载个人目录。

  • SHARE - 仅挂载共享目录。

  • ANY - 挂载目录不做限制(个人和共享NAS存储目录都会自动挂载)。

enterprise_project_id

String

企业项目ID(0表示默认企业项目Id)。

primary_server_group_ids

Array of strings

主服务器组id列表。

secondary_server_group_ids

Array of strings

备服务器组id列表。

server_group_status

Boolean

服务器是否处于启用状态，true表示处于启用状态 false表示处于禁用状态。

site_type

String

站点类型 - CENTER/IES。

site_id

String

站点id。

app_server_flavor_count

Integer

服务器配置总数量。

app_server_count

Integer

服务器总数量。

app_group_count

Integer

关联应用组的总数量。

image_name

String

镜像名称。

product_info

ProductInfo object

产品规格信息。

subnet_name

String

子网名称。

scaling_policy

ScalingPolicy object

弹性伸缩策略。

tags

Array of TmsTag objects

标签信息。

ou_name

String

默认组织名称。
表8 ProductInfo

参数

参数类型

描述

product_id

String

产品id。

flavor_id

String

规格ID。

type

String

产品类型：

  • BASE：表示产品基础套餐，套餐镜像中不包括除操作系统之外的其他商业软件，私有镜像场景只能使用此类套餐。

  • ADVANCED：表示产品高级套餐，套餐镜像中包括了一些商业软件。

architecture

String

产品架构，当前仅支持x86。

  • x86

  • arm

cpu

String

CPU。

cpu_desc

String

CPU描述。

memory

String

内存大小，单位兆：M。

is_gpu

Boolean

是否是GPU类型的规格。

system_disk_type

String

系统盘类型。

system_disk_size

String

系统盘大小。

gpu_desc

String

GPU描述。

descriptions

String

产品描述。

charge_mode

String

套餐标识。

  • 1：表示包周期。

  • 0：表示按需。

contain_data_disk

Boolean

套餐计费是否包含了数据盘。

resource_type

String

资源类型。

cloud_service_type

String

云服务类型。

volume_product_type

String

磁盘产品类型。

sessions

Integer

套餐默认支持的最大会话数。

status

String

产品套餐在销售模式下的状态，取值自ECS的cond:operation:status。

不配置时等同于normal在售状态。

  • normal - 正常商用

  • abandon - 下线（即不显示）

  • sellout - 售罄

  • obt - 公测

  • obt_sellout - 公测售罄

  • promotion - 推荐(等同normal，也是商用)

cond_operation_az

String

产品套餐在可用区的状态，配套status使用。

说明：

  • 此参数是AZ级配置，优选取此参数的值，某个AZ没有在此参数中配置时默认使用status参数的取值。

  • 配置格式“az(xx)”。()内为某个AZ的flavor状态，()内必须要填有状态，不填为无效配置。

  • 例如：套餐在某个region的az0正常商用，az1售罄，az2公测，az3正常商用，其他az显示下线，可配置为：

    • “status”设置为：“abandon” 。

    • “cond_operation_az”设置为：“az0(normal), az1(sellout), az2(obt), az3(normal)”。

  • 说明：如果flavor在某个AZ下的状态与status配置状态不同，必须配置该参数。

sub_product_list

Array of strings

专属主机的子产品。

domain_ids

Array of strings

产品属于专有的domainId。

package_type

String

套餐类型：

  • general：表示产品通用套餐。

  • dedicated：表示产品专属主机套餐。

expire_time

String

产品套餐过期时间，产品将在该时间点后逐步下架。

support_gpu_type

String

产品套餐支持的GPU类型。
表9 ScalingPolicy

参数

参数类型

描述

enable

Boolean

是否启用策略,默认启用：

'true': 启用

'false': 禁用

max_scaling_amount

Integer

最大扩容数量。

single_expansion_count

Integer

单次扩容数量。

scaling_policy_by_session

ScalingPolicyBySession object

基于会话的弹性策略。
表10 ScalingPolicyBySession

参数

参数类型

描述

session_usage_threshold

Integer

分组的总会话使用率(达到该阈值后扩容)。

shrink_after_session_idle_minutes

Integer

给定时间内无会话连接的的实例进行释放。
表11 TmsTag

参数

参数类型

描述

key

String

键。最大长度128个unicode字符。

  1. 可用 UTF-8 格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格，以及以下字符： _ . : = + - @。

  2. 两头不能有空白字符。

value

String

值。每个值最大长度255个unicode字符。

  1. 可用 UTF-8 格式表示的字母(包含中文、西班牙语、葡语等)、数字和空格，以及以下字符： _ . : = + - @。

状态码：400

表12 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：401

表13 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：403

表14 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：404

表15 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：405

表16 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：500

表17 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

状态码：503

表18 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

请求示例

POST /v1/a4da8115c9d8464ead3a38309130523f/app-server-groups

{
  "name" : "APIExplore测试应用服务器组",
  "image_id" : "",
  "os_type" : "Windows",
  "image_type" : "private",
  "image_product_id" : "00301-2019002-0--0",
  "description" : "",
  "route_policy" : {
    "max_session" : 1
  },
  "product_id" : "workspace.appstream.general.xlarge.2",
  "subnet_id" : "a5842cb4-5718-4b0a-8b27-3a3e9c74f977",
  "system_disk_type" : "SATA",
  "system_disk_size" : 60,
  "vpc_id" : "59785ba5-e5d5-4836-b9de-19f22ac15175",
  "ip_virtual" : {
    "enable" : false
  },
  "is_vdi" : false,
  "availability_zone" : "",
  "app_type" : "COMMON_APP",
  "extra_session_type" : "GPU",
  "extra_session_size" : 1,
  "primary_server_group_id" : "e5d5-4836-b9de-19f22ac15175",
  "server_group_status" : false
}

响应示例

状态码：200

成功响应。

{
  "id" : "bc05da52-89df-45ba-8146-13fe3ce7c45a",
  "name" : "ApiExpirezSr5_20230606221433888186",
  "description" : "",
  "image_id" : "0fd6c925-6349-49d6-8788-48263b129854",
  "os_type" : "Windows",
  "product_id" : "workspace.appstream.general.xlarge.2",
  "subnet_id" : "a5842cb4-5718-4b0a-8b27-3a3e9c74f977",
  "system_disk_type" : "SATA",
  "system_disk_size" : 60,
  "is_vdi" : false,
  "create_time" : "2023-06-06T14:14:36.416Z",
  "update_time" : "2023-06-06T14:14:36.416Z",
  "ou_name" : "",
  "extra_session_type" : "GPU",
  "extra_session_size" : 1,
  "app_type" : "COMMON_APP"
}

状态码

状态码

描述

200

成功响应。

400

由于包含语法错误，当前请求无法被服务器理解。

401

鉴权失败。

403

没有操作权限。

404

找不到资源。

405

请求中指定的方法不被允许。

500

服务内部错误，具体返回错误码请参见错误码说明。

503

服务不可用。

错误码

请参见错误码。

父主题： 服务器组管理

相关文档