文档首页/ 弹性云服务器 ECS/ API参考（吉隆坡区域）/ API（推荐）/ 生命周期管理/ 创建云服务器

更新时间：2024-07-23 GMT+08:00

查看PDF

创建云服务器

功能介绍

创建一台或多台云服务器。

本接口为异步接口，当前创建云服务器请求下发成功后会返回job_id，此时创建云服务器并没有立即完成，需要通过调用查询任务的执行状态查询job状态，当Job状态为 SUCCESS 时代表云服务器创建成功。

调用接口前，您需要了解API认证鉴权。

调用接口前，您需要提前获取到地区和终端节点。

弹性云服务器的登录鉴权方式包括两种：密钥对、密码。为安全起见，推荐使用密钥对方式。

密钥对
 指使用密钥对作为弹性云服务器的鉴权方式。

接口调用方法：使用key_name字段，指定弹性云服务器登录时使用的密钥文件。
密码
 指使用设置初始密码方式作为弹性云服务器的鉴权方式，此时，您可以通过用户名密码方式登录弹性云服务器，Linux操作系统时为root用户的初始密码，Windows操作系统时为Administrator用户的初始密码。

接口调用方法：使用adminPass字段，指定管理员账号的初始登录密码，adminPass字段的使用方法请参见表3。对于镜像已安装Cloud-init的Linux云服务器，如果需要使用密文密码，可以使用user_data字段进行密码注入，具体请参见表3。

对于安装Cloud-init镜像的Linux云服务器，若指定user_data字段，则该adminPass字段无效。
镜像密码
 使用Linux操作系统私有镜像创建云服务器，支持使用私有镜像的密码。

接口调用方法：使用镜像密码，则无需指定key_name、adminPass字段。

URI

POST /v1/{project_id}/cloudservers

参数说明请参见表1。

表1 参数说明
参数	是否必选	描述
project_id	是	项目ID。获取方法请参见获取项目ID。

请求消息

请求参数

请求参数如表2所示。

表2 请求参数
参数	是否必选	参数类型	描述
server	是	Object	弹性云服务器信息，请参见表3。
dry_run	否	Boolean	是否只预检此次请求，默认为false。 true：发送检查请求，不会创建实例。检查项包括是否填写了必需参数、请求格式等。如果检查不通过，则返回对应错误。如果检查通过，则返回202状态码。 false：发送正常请求，通过检查后并且执行创建云服务器请求。

表3 创建云服务器请求参数说明
参数	是否必选	参数类型	描述
imageRef	是	String	待创建云服务器的系统镜像，需要指定已创建镜像的ID，ID格式为通用唯一识别码（Universally Unique Identifier，简称UUID）。
flavorRef	是	String	待创建云服务器的系统规格的ID。已上线的规格请参见《弹性云服务器用户指南》的“实例类型与规格”章节。
name	是	String	云服务器名称。取值范围：只能由中文字符、英文字母、数字及“_”、“-”、“.”组成，且长度为[1-128]个英文字符或[1-64]个中文字符。创建的云服务器数量（count字段对应的值）大于1时，为区分不同云服务器，创建过程中系统会自动在名称后加“-0000”的类似标记。若用户在名称后已指定“-0000”的类似标记，系统将从该标记后继续顺序递增编号。故此时名称的长度为[1-59]个字符。说明：云服务器虚拟机内部(hostname)命名规则遵循 RFC 952和RFC 1123命名规范，建议使用a-z或0-9以及中划线"-"组成的名称命名，"_"将在弹性云服务器内部默认转化为"-"。
user_data	否	String	创建云服务器过程中待注入实例自定义数据。支持注入文本、文本文件。说明： user_data的值为base64编码之后的内容。注入内容（编码之前的内容）最大长度为32K。更多关于待注入实例自定义数据的信息，请参见《弹性云服务器用户指南》的“实例自定义数据注入”章节。示例： base64编码前： Linux服务器： #!/bin/bash echo user_test > /home/user.txt Windows服务器： rem cmd echo 111 > c:\aaa.txt base64编码后： Linux服务器： IyEvYmluL2Jhc2gKZWNobyB1c2VyX3Rlc3QgPiAvaG9tZS91c2VyLnR4dA== Windows服务器： cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ=
adminPass	否	String	如果需要使用密码方式登录云服务器，可使用adminPass字段指定云服务器管理员账户初始登录密码。其中，Linux管理员账户为root，Windows管理员账户为Administrator。密码复杂度要求：长度为8-26位。密码至少必须包含大写字母、小写字母、数字和特殊字符（!@$%^-_=+[{}]:,./?~#*）中的三种。密码不能包含用户名或用户名的逆序。 Windows系统密码不能包含用户名或用户名的逆序，不能包含用户名中超过两个连续字符的部分。
key_name	否	String	如果需要使用SSH密钥方式登录云服务器，请指定已创建密钥的名称。密钥可以通过密钥创建接口进行创建（请参见创建和导入SSH密钥），或使用SSH密钥查询接口查询已有的密钥（请参见查询SSH密钥列表）。
vpcid	是	String	待创建云服务器所属虚拟私有云（简称VPC），需要指定已创建VPC的ID，UUID格式。 VPC的ID可以从控制台或者参考《虚拟私有云接口参考》的“查询VPC”章节获取。
nics	是	Array of objects	待创建云服务器的网卡信息。详情请参见表4。约束：需要指定vpcid对应VPC下已创建的子网（subnet）的网络ID，UUID格式。当前单个云服务器支持最多挂载12张网卡。
publicip	否	Object	配置云服务器的弹性公网IP信息，弹性公网IP有三种配置方式。不使用（无该字段）自动分配，需要指定新创建弹性公网IP的信息使用已有，需要指定已创建弹性公网IP的信息详情请参见表1。
count	否	Integer	创建云服务器数量。约束：不传该字段时默认取值为1。租户的配额足够时，最大值为500。
root_volume	是	Object	云服务器对应系统盘相关配置。详情请参见表5。
data_volumes	否	Array of objects	云服务器对应数据盘相关配置。每一个数据结构代表一块待创建的数据盘。约束：目前云服务器最多可挂载59块数据盘(部分规格只支持23块数据盘）详情请参见表6。
security_groups	否	Array of objects	云服务器对应安全组信息。约束：当该值指定为空时，默认给云服务器绑定default安全组。详情请参见表2。
availability_zone	否	String	待创建云服务器所在的可用区，需要指定可用分区名称。说明：如果为空，会自动指定一个符合要求的可用区。如果在专属主机上创建云服务器，需指定云服务器与专属主机所在可用区一致。
extendparam	否	Object	创建云服务器附加信息。详情请参见表7。
metadata	否	Map<String,String>	创建云服务器元数据。可以通过元数据自定义键值对。说明：如果元数据中包含了敏感数据，您应当采取适当的措施来保护敏感数据，比如限制访问范围、加密等。最多可注入10对键值（Key/Value）。主键（Key）只能由大写字母（A-Z）、小写字母（a-z）、数字（0-9）、中划线（-）、下划线（_）、冒号（:）、空格（）和小数点（.）组成，长度为[1-255]个字符。值（value）最大长度为255个字符。系统预留键值对请参见表9。
tags	否	Array of strings	弹性云服务器的标签。标签的格式为“key.value”。其中，key的长度不超过36个字符，value的长度不超过43个字符。标签命名时，需满足如下要求：说明：创建弹性云服务器时，一台弹性云服务器最多可以添加10个标签。
description	否	String	云服务器描述信息，默认为空字符串。长度最多允许85个字符。不能包含“<” 和 “>”。

表4 nics字段数据结构说明
参数	是否必选	参数类型	描述
subnet_id	是	String	待创建云服务器所在的子网信息。需要指定vpcid对应VPC下已创建的子网（subnet）的网络ID，UUID格式。
ip_address	否	String	待创建云服务器网卡的IP地址，IPv4格式。约束：不填或空字符串，默认在子网（subnet）中自动分配一个未使用的IP作网卡的IP地址。若指定IP地址，该IP地址必须在子网（subnet）对应的网段内，且未被使用。
ipv6_enable	否	Boolean	是否支持ipv6。取值为true时，表示此网卡支持ipv6。
ipv6_bandwidth	否	Object	绑定的共享带宽信息，详情请参见ipv6_bandwidth字段数据结构说明。

表5 root_volume字段数据结构说明
参数	是否必选	参数类型	描述
volumetype	是	String	云服务器系统盘对应的磁盘类型，需要与系统所提供的磁盘类型相匹配。目前支持“SSD”，“SAS”三种。 “SSD”为超高IO云硬盘 “SAS”为高IO云硬盘当指定的云硬盘类型在availability_zone内不存在时，则创建云硬盘失败。说明：了解不同磁盘类型的详细信息，请参见“云硬盘用户指南 > 磁盘类型及性能介绍”。
size	否	Integer	系统盘大小，容量单位为GB，输入大小范围为[1,1024]。约束：系统盘大小取值应不小于镜像支持的系统盘的最小值(镜像的min_disk属性)。若该参数没有指定或者指定为0时，系统盘大小默认取值为镜像中系统盘的最小值(镜像的min_disk属性)。说明：镜像系统盘的最小值（镜像的min_disk属性）可在控制台上单击镜像详情查看。或通过调用“查询镜像详情（OpenStack原生）”API获取，详细操作请参考《镜像服务API参考》中“查询镜像详情（OpenStack原生）”章节。
extendparam	否	Object	磁盘的产品信息。详情请参见创建磁盘的extendparam字段数据结构说明。
hw:passthrough	否	Boolean	设置云硬盘的设备类型：参数指定为false，创建VBD类型磁盘。参数指定为true，创建SCSI类型磁盘。参数未指定或者指定非Boolean类型的字符，默认创建VBD类型磁盘。

表6 data_volumes字段数据结构说明
参数	是否必选	参数类型	描述
volumetype	是	String	云服务器数据盘对应的磁盘类型，需要与系统所提供的磁盘类型相匹配。目前支持“SSD”，“SAS”三种。 “SSD”为超高IO云硬盘 “SAS”为高IO云硬盘当指定的云硬盘类型在availability_zone内不存在时，则创建云硬盘失败。说明：了解不同磁盘类型的详细信息，请参见“云硬盘用户指南 > 磁盘类型及性能介绍”。
size	是	Integer	数据盘大小，容量单位为GB，输入大小范围为[10,32768]。如果使用数据盘镜像创建数据盘时，size取值不能小于创建数据盘镜像的源数据盘的大小。
shareable	否	Boolean	是否为共享磁盘。true为共享盘，false为普通云硬盘。说明：该字段已废弃，请使用multiattach。
multiattach	否	Boolean	创建共享磁盘的信息。 true：创建的磁盘为共享盘。 false：创建的磁盘为普通云硬盘。说明： shareable当前为废弃字段，如果确实需要同时使用shareable字段和multiattach字段，此时，请确保两个字段的参数值相同。当不指定该字段时，系统默认创建普通云硬盘。
hw:passthrough	否	Boolean	设置云硬盘的设备类型：参数指定为false，创建VBD类型磁盘。参数指定为true，创建SCSI类型磁盘。参数未指定或者指定非Boolean类型的字符，默认创建VBD类型磁盘。
extendparam	否	Object	磁盘的产品信息。详情请参见表6。
data_image_id	否	String	数据镜像的ID，UUID格式。如果使用数据盘镜像创建数据盘，则data_image_id为必选参数，且不支持使用metadata。
metadata	否	Object	创建云硬盘的metadata信息，metadata中的key和value长度不大于255个字节。仅在创建加密盘时使用metadata字段。如果使用数据盘镜像创建数据盘，不支持使用metadata。详情请参见创建磁盘的metadata字段数据结构说明

响应消息

参数	参数类型	描述
job_id	String	提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态，请参考5.8 查询Job状态。

异常响应请参考响应（任务类），异常响应要素说明。

请求示例

创建一台按需计费云服务器，操作系统为CentOS 7.6 64bit，4U8G，磁盘类型为“SSD”，绑定10M的按带宽计费的弹性公网IP，采用密钥方式登录鉴权。

POST https://{endpoint}/v1/{project_id}/cloudservers

{
    "server": {
        "availability_zone":"az1-dc1",
        "name": "newserver", 
        "imageRef": "67f433d8-ed0e-4321-a8a2-a71838539e09", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [ 
            {
                "volumetype": "SSD", 
                "size": 100,
                "multiattach": true,
                "hw:passthrough": true
            }
        ], 
        "flavorRef": "s3.xlarge.2", 
        "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
        "security_groups": [
            {
                "id": "507ca48f-814c-4293-8706-300564d54620"
            }
        ], 
        "nics": [
            {
                "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83"
            }
        ], 
        "publicip": {
            "eip": {
                "iptype": "5_bgp",
                "bandwidth": {
                    "size": 10, 
                    "sharetype": "PER"
                }
            }
        }, 
        "key_name": "sshkey-123", 
        "count": 1, 
        "server_tags": [
            {
                "key": "key1",
                "value": "value1"
            }
        ],
        "metadata": {
               "op_svc_userid": "8ea65f4099ba412883e2a0da72b96873",
               "agency_name": "test"
        }
    }
}

发送预校验请求，检查创建弹性云服务器的请求消息是否填写了必选参数，请求格式是否正确。

POST https://{endpoint}/v1/{project_id}/cloudservers

{
    "dry_run": true,
    "server": {
        "availability_zone":"az1-dc1",
        "name": "newserver", 
        "imageRef": "1189efbf-d48b-46ad-a823-94b942e2a000", 
        "root_volume": {
            "volumetype": "SSD"
        }, 
        "data_volumes": [
            {                 
                 "volumetype": "SSD",                  
                 "size": 100,                 
                 "multiattach": true,                 
                 "hw:passthrough": true             
            }
        ], 
        "flavorRef": "s3.xlarge.2", 
        "vpcid": "0dae26c9-9a70-4392-93f3-87d53115d171", 
        "security_groups": [
            {
                "id": "507ca48f-814c-4293-8706-300564d54620"
            }
        ], 
        "nics": [
            {
                "subnet_id": "157ee789-03ea-45b1-a698-76c92660dd83"
            }
        ], 
        "key_name": "sshkey-123", 
        "count": 1
    }
}

响应示例

{
    "job_id": "93c82933d6b7827d3016b8771f2070873"
}

或

{
    "error": {
        "code": "request body is illegal.", 
        "message": "Ecs.0005"
    }
}

或

{
    "error": {
        "message": "privateIp [%s] is not in this subnet [%s]",
        "code": "Ecs.0005",
        "details": [
            {
                "code": "Ecs.0039"
            }
        ]
    }
}

返回值

请参考通用请求返回值。

错误码

请参考错误码。

父主题： 生命周期管理

上一篇：生命周期管理

下一篇：删除云服务器

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消