功能介紹
創(chuàng)建一臺或多臺按需付費方式的 云服務(wù)器 。
本接口為異步接口，當前創(chuàng)建云服務(wù)器請求下發(fā)成功后會返回job_id，此時創(chuàng)建云服務(wù)器并沒有立即完成，需要通過調(diào)用查詢?nèi)蝿?wù)的執(zhí)行狀態(tài)查詢job狀態(tài)，當Job狀態(tài)為 SUC CES S 時代表云服務(wù)器創(chuàng)建成功。
本接口支持在HTTP請求消息頭中設(shè)置X-Client-Token請求頭，保證請求冪等性。詳細信息請參考請求冪等性說明。
調(diào)用接口前，您需要了解API認證鑒權(quán)。
調(diào)用接口前，您需要提前獲取到地區(qū)和終端節(jié)點。
彈性云服務(wù)器的登錄鑒權(quán)方式包括兩種：密鑰對、密碼。為安全起見，推薦使用密鑰對方式。
- 密鑰對
指使用密鑰對作為彈性云服務(wù)器的鑒權(quán)方式。
接口調(diào)用方法：使用key_name字段，指定彈性云服務(wù)器登錄時使用的密鑰文件。
- 密碼
指使用設(shè)置初始密碼方式作為彈性云服務(wù)器的鑒權(quán)方式，此時，您可以通過用戶名密碼方式登錄彈性云服務(wù)器，Linux操作系統(tǒng)時為root用戶的初始密碼，Windows操作系統(tǒng)時為Administrator用戶的初始密碼。
接口調(diào)用方法：使用adminPass字段，指定管理員帳號的初始登錄密碼，adminPass字段的使用方法請參見表3。對于 鏡像 已安裝Cloud-init的Linux云服務(wù)器，如果需要使用密文密碼，可以使用user_data字段進行密碼注入，具體請參見表3。
對于安裝Cloud-init鏡像的Linux云服務(wù)器，若指定user_data字段，則該adminPass字段無效。
- 鏡像密碼
使用Linux操作系統(tǒng)私有鏡像創(chuàng)建云服務(wù)器，支持使用私有鏡像的密碼。
接口調(diào)用方法：使用鏡像密碼，則無需指定key_name、adminPass字段。
接口約束
創(chuàng)建按需計費云服務(wù)器時，系統(tǒng)會自動匹配適用的代金券進行使用。
調(diào)試
您可以在API Explorer中調(diào)試該接口。
請求消息
請求參數(shù)
|
參數(shù) |
是否必選 |
參數(shù)類型 |
描述 |
|---|---|---|---|
|
server |
是 |
Object |
|
|
dry_run |
否 |
Boolean |
是否只預(yù)檢此次請求，默認為false。
|
|
參數(shù) |
是否必選 |
參數(shù)類型 |
描述 |
|---|---|---|---|
|
imageRef |
是 |
String |
待創(chuàng)建云服務(wù)器的系統(tǒng)鏡像，需要指定已創(chuàng)建鏡像的ID，ID格式為通用唯一識別碼（Universally Unique Identifier，簡稱UUID）。 |
|
flavorRef |
是 |
String |
待創(chuàng)建云服務(wù)器的系統(tǒng)規(guī)格的ID。 已上線的規(guī)格請參見《彈性云服務(wù)器產(chǎn)品介紹》的“實例類型與規(guī)格”章節(jié)。 |
|
name |
是 |
String |
云服務(wù)器名稱。 創(chuàng)建的云服務(wù)器數(shù)量（count字段對應(yīng)的值）等于1時，云服務(wù)器名稱只能由中文字符、英文字母、數(shù)字及“_”、“-”組成，且長度為[1-64]個字符。 創(chuàng)建的云服務(wù)器數(shù)量（count字段對應(yīng)的值）大于1時，可以使用“自動排序”和“正則排序”設(shè)置有序的云服務(wù)器名稱。 請參考創(chuàng)建多臺云服務(wù)器云主機時怎樣設(shè)置有序的云服務(wù)器云主機名稱？ 取值范圍：
|
|
user_data |
否 |
String |
創(chuàng)建云服務(wù)器過程中待注入實例自定義數(shù)據(jù)。支持注入文本、文本文件。 說明：
更多關(guān)于待注入實例自定義數(shù)據(jù)的信息，請參見《彈性云服務(wù)器用戶指南 》的“用戶數(shù)據(jù)注入”章節(jié)。 示例： base64編碼前：
base64編碼后：
|
|
adminPass |
否 |
String |
如果需要使用密碼方式登錄云服務(wù)器，可使用adminPass字段指定云服務(wù)器管理員帳戶初始登錄密碼。其中，Linux管理員帳戶為root，Windows管理員帳戶為Administrator。 密碼復(fù)雜度要求：
|
|
key_name |
否 |
String |
如果需要使用SSH密鑰方式登錄云服務(wù)器，請指定已創(chuàng)建密鑰的名稱。 密鑰可以通過密鑰創(chuàng)建接口進行創(chuàng)建（請參見 創(chuàng)建和導(dǎo)入SSH密鑰），或使用SSH密鑰查詢接口查詢已有的密鑰（請參見查詢SSH密鑰列表 ）。 |
|
vpcid |
是 |
String |
待創(chuàng)建云服務(wù)器所屬 虛擬私有云 （簡稱VPC），需要指定已創(chuàng)建VPC的ID，UUID格式。 |
|
nics |
是 |
Array of objects |
待創(chuàng)建云服務(wù)器的網(wǎng)卡信息。詳情請參見表4。 約束：
|
|
publicip |
否 |
Object |
配置云服務(wù)器的 彈性公網(wǎng)IP 信息，彈性 公網(wǎng)IP 有三種配置方式。
詳情請參見表1。 |
|
count |
否 |
Integer |
創(chuàng)建云服務(wù)器數(shù)量。 約束：
|
|
isAutoRename |
否 |
Boolean |
當批量創(chuàng)建彈性云服務(wù)器時，云服務(wù)器名稱是否允許重名，當count大于1的時候該參數(shù)生效。默認為False。
|
|
root_volume |
是 |
Object |
云服務(wù)器對應(yīng)系統(tǒng)盤相關(guān)配置。 |
|
data_volumes |
否 |
Array of objects |
云服務(wù)器對應(yīng)數(shù)據(jù)盤相關(guān)配置。每一個數(shù)據(jù)結(jié)構(gòu)代表一塊待創(chuàng)建的數(shù)據(jù)盤。 約束：目前云服務(wù)器最多可掛載59塊數(shù)據(jù)盤(部分規(guī)格只支持23塊數(shù)據(jù)盤） |
|
security_groups |
否 |
Array of objects |
云服務(wù)器對應(yīng)安全組信息。 約束：當該值指定為空時，默認給云服務(wù)器綁定default安全組。 詳情請參見表2。 |
|
availability_zone |
否 |
String |
待創(chuàng)建云服務(wù)器所在的可用區(qū)，需要指定可用分區(qū)名稱。 說明：
如果為空，會自動指定一個符合要求的可用區(qū)。 可通過接口 查詢可用區(qū)列表 獲取，也可參考地區(qū)和終端節(jié)點獲取。 |
|
batch_create_in_multi_az |
否 |
Boolean |
是否支持隨機多AZ部署，默認為false。
當availability_zone為空時該字段生效。 |
|
extendparam |
否 |
Object |
創(chuàng)建云服務(wù)器附加信息。 詳情請參見表8。 |
|
metadata |
否 |
Map<String,String> |
創(chuàng)建云服務(wù)器元數(shù)據(jù)。 可以通過元數(shù)據(jù)自定義鍵值對。 說明：
系統(tǒng)預(yù)留鍵值對請參見表11。 |
|
os:scheduler_hints |
否 |
Object |
云服務(wù)器調(diào)度信息，例如設(shè)置云服務(wù)器組。 詳情請參見表12。 |
|
tags |
否 |
Array of strings |
彈性云服務(wù)器的標簽。 標簽的格式為“key.value”。其中，key的長度不超過36個字符，value的長度不超過43個字符。 標簽命名時，需滿足如下要求：
說明：
|
|
server_tags |
否 |
Array of objects |
彈性云服務(wù)器的標簽。詳情請參見表14。 說明：
|
|
description |
否 |
String |
云服務(wù)器描述信息，默認為空字符串。
|
|
auto_terminate_time |
否 |
String |
該字段尚不支持，功能即將上線，敬請期待。 自動釋放時間。 按照ISO8601標準表示，并使用UTC +0時間，格式為yyyy-MM-ddTHH:mm:ssZ。 如果秒（ss）取值不是 00，則自動取為當前分鐘（mm）開始時。 最短釋放時間為當前時間半小時之后。 最長釋放時間不能超過當前時間三年。 示例：2020-09-25T12:05:00Z 說明：
僅按需實例支持設(shè)置自動釋放時間。 |
|
參數(shù) |
是否必選 |
參數(shù)類型 |
描述 |
|---|---|---|---|
|
subnet_id |
是 |
String |
待創(chuàng)建云服務(wù)器所在的子網(wǎng)信息。 需要指定vpcid對應(yīng)VPC下已創(chuàng)建的子網(wǎng)（subnet）的網(wǎng)絡(luò)ID，UUID格式。 可以通過VPC服務(wù)查詢子網(wǎng)列表接口查詢。 |
|
ip_address |
否 |
String |
待創(chuàng)建云服務(wù)器網(wǎng)卡的IP地址，IPv4格式。 約束：
|
|
ipv6_enable |
否 |
Boolean |
是否支持ipv6。取值為true時，表示此網(wǎng)卡支持ipv6。 |
|
ipv6_bandwidth |
否 |
Object |
綁定的共享帶寬信息，詳情請參見ipv6_bandwidth字段數(shù)據(jù)結(jié)構(gòu)說明。 |
|
allowed_address_pairs |
否 |
約束：IP地址不允許為 “0.0.0.0/0”
|
|
名稱 |
是否必選 |
參數(shù)類型 |
說明 |
|---|---|---|---|
|
ip_address |
否 |
String |
IP地址。 約束：不支持0.0.0.0/0 如果allowed_address_pairs配置地址池較大的CIDR（掩碼小于24位），建議為該port配置一個單獨的安全組。 |
|
mac_address |
否 |
String |
MAC地址。 |
|
參數(shù) |
是否必選 |
參數(shù)類型 |
描述 |
|---|---|---|---|
|
volumetype |
是 |
String |
云服務(wù)器系統(tǒng)盤對應(yīng)的磁盤類型，需要與系統(tǒng)所提供的磁盤類型相匹配。 目前支持“SATA”，“SAS”，“GPSSD”，“SSD”，“ESSD”。
當指定的云硬盤類型在avaliability_zone內(nèi)不存在時，則創(chuàng)建云硬盤失敗。 說明：
|
|
size |
否 |
Integer |
系統(tǒng)盤大小，容量單位為GB， 輸入大小范圍為[1,1024]。 約束：
|
|
extendparam |
否 |
Object |
磁盤的產(chǎn)品信息。 |
|
cluster_type |
否 |
String |
云服務(wù)器系統(tǒng)盤對應(yīng)的磁盤存儲類型。 磁盤存儲類型枚舉值：DSS（專屬存儲類型） 該參數(shù)需要與“cluster_id”配合使用，僅當“cluster_id”不為空時，才可以成功創(chuàng)建專屬存儲類型的磁盤。 |
|
cluster_id |
否 |
String |
云服務(wù)器系統(tǒng)盤對應(yīng)的存儲池的ID。 |
|
hw:passthrough |
否 |
Boolean |
設(shè)置云硬盤的設(shè)備類型：
說明：
非擎天規(guī)格僅支持設(shè)置系統(tǒng)盤為VBD類型。 |
|
metadata |
否 |
Object |
創(chuàng)建云硬盤的metadata信息，metadata中的key和value長度不大于255個字節(jié)。 僅在創(chuàng)建加密盤時使用metadata字段。 |
|
參數(shù) |
是否必選 |
參數(shù)類型 |
描述 |
|---|---|---|---|
|
volumetype |
是 |
String |
云服務(wù)器數(shù)據(jù)盤對應(yīng)的磁盤類型，需要與系統(tǒng)所提供的磁盤類型相匹配。 目前支持“SATA”，“SAS”，“GPSSD”，“SSD”，“ESSD”。
當指定的云硬盤類型在avaliability_zone內(nèi)不存在時，則創(chuàng)建云硬盤失敗。 說明：
|
|
size |
是 |
Integer |
數(shù)據(jù)盤大小，容量單位為GB，輸入大小范圍為[10,32768]。 如果使用數(shù)據(jù)盤鏡像創(chuàng)建數(shù)據(jù)盤時，size取值不能小于創(chuàng)建數(shù)據(jù)盤鏡像的源數(shù)據(jù)盤的大小。 |
|
shareable |
否 |
Boolean |
是否為共享磁盤。true為共享盤，false為普通云硬盤。 說明：
該字段已廢棄，請使用multiattach。 |
|
multiattach |
否 |
Boolean |
創(chuàng)建共享磁盤的信息。
說明：
|
|
hw:passthrough |
否 |
Boolean |
設(shè)置云硬盤的設(shè)備類型：
說明：
非擎天規(guī)格僅支持設(shè)置系統(tǒng)盤為VBD類型。 |
|
extendparam |
否 |
Object |
磁盤的產(chǎn)品信息。 詳情請參見表7。 |
|
cluster_type |
否 |
String |
云服務(wù)器數(shù)據(jù)盤對應(yīng)的磁盤存儲類型。 磁盤存儲類型枚舉值：DSS（專屬存儲類型） 該參數(shù)需要與“cluster_id”配合使用，僅當“cluster_id”不為空時，才可以成功創(chuàng)建專屬存儲類型的磁盤。 |
|
cluster_id |
否 |
String |
云服務(wù)器數(shù)據(jù)盤對應(yīng)的存儲池的ID。 |
|
data_image_id |
否 |
String |
數(shù)據(jù)鏡像的ID，UUID格式。 如果使用數(shù)據(jù)盤鏡像創(chuàng)建數(shù)據(jù)盤，則data_image_id為必選參數(shù)，且不支持使用metadata。 |
|
metadata |
否 |
Object |
創(chuàng)建云硬盤的metadata信息，metadata中的key和value長度不大于255個字節(jié)。 僅在創(chuàng)建加密盤時使用metadata字段。 如果使用數(shù)據(jù)盤鏡像創(chuàng)建數(shù)據(jù)盤，不支持使用metadata。 |
|
delete_on_termination |
否 |
Boolean |
數(shù)據(jù)盤隨實例釋放策略
默認值：false 說明：
該字段僅按需、競價實例支持。 |
響應(yīng)消息
|
參數(shù) |
參數(shù)類型 |
描述 |
|---|---|---|
|
job_id |
String |
提交任務(wù)成功后返回的任務(wù)ID，用戶可以使用該ID對任務(wù)執(zhí)行情況進行查詢。如何根據(jù)job_id來查詢Job的執(zhí)行狀態(tài)，請參考5.8 查詢Job狀態(tài)。 |
|
serverIds |
Array of strings |
云服務(wù)器ID列表。 說明：
通過云服務(wù)器ID查詢云服務(wù)器詳情 ，若返回404 可能云服務(wù)器還在創(chuàng)建或者已經(jīng)創(chuàng)建失敗。 |
異常響應(yīng)請參考響應(yīng)（任務(wù)類），異常響應(yīng)要素說明。
請求示例
- 創(chuàng)建一臺按需計費云服務(wù)器，操作系統(tǒng)為CentOS 7.6 64bit，4U8G，磁盤類型為“SSD”，綁定10M的按帶寬計費的彈性公網(wǎng)IP，采用密鑰方式登錄鑒權(quán)。
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, "extendparam": { "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb" }, "server_tags": [ { "key": "key1", "value": "value1" } ], "metadata": { "op_svc_userid": "8ea65f4099ba412883e2a0da72b96873", "agency_name": "test" } } } - 發(fā)送預(yù)校驗請求，檢查創(chuàng)建彈性云服務(wù)器的請求消息是否填寫了必選參數(shù)，請求格式是否正確。
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 } }
響應(yīng)示例
或
{
"job_id": "ff808082739334d80173941567f21d4f",
"serverIds": [
"118258c5-0c6a-4e73-8b51-8d1ea3272e1b",
"e51b9e20-7088-4914-a4f3-6c76bcfed0be"
]
}
或
{
"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"
}
]
}
}
返回值
請參考通用請求返回值。
錯誤碼
請參考錯誤碼。
