CreateImage - Elastic Compute Service

建立一份自訂映像。後續您可以使用建立的自訂映像建立ECS執行個體（RunInstances），或者更換執行個體的系統磁碟（ReplaceSystemDisk）。

介面說明

注意事項

本介面為非同步介面，建立自訂映像請求傳送成功後會傳回映像 ID，映像的建立不是立即完成的，需要呼叫 DescribeImage 檢視映像資訊，當傳回資訊中的狀態為Available時代表映像建立成功並可用。更多資訊，請參閱自訂映像概述。
查詢 ECS 執行個體資訊時，如果傳回資料中包含{"OperationLocks": {"LockReason" : "security"}}，則禁止建立自訂映像。
建議在建立映像時設定映像檢測參數DetectionStrategy，有助於系統協助最佳化您的映像。更多資訊，請參閱映像檢測概述。

以下描述了三種透過該介面建立自訂映像的方法。請求參數的優先順序為：InstanceId > DiskDeviceMapping > SnapshotId，若您的請求中同時含有兩個及以上參數，預設以優先順序更高的參數為準建立映像。

根據執行個體建立自訂映像：指定執行個體 ID（InstanceId）。
- 執行個體的狀態必須為執行中（Running）或者已停止（Stopped）。
- 介面呼叫成功後，執行個體的每塊雲端硬碟均會新增一份快照。
重要由於執行中的執行個體存在快取資料未落碟的情況，可能導致建立的自訂映像資料與執行個體資料不完全一致，因此建議您停止執行個體（ StopInstances ）後建立映像。
根據快照建立自訂映像（指定的快照不能是 2013 年 7 月 15 日（含）之前建立的快照。）
- 使用系統磁碟快照建立自訂映像：只需指定執行個體系統磁碟的快照 ID（SnapshotId）。
- 使用系統磁碟快照和資料磁碟快照建立自訂映像：這需要建立幾塊雲端硬碟的資料關聯（DiskDeviceMapping）。
  - 系統磁碟快照只能被指定一個。
  - 資料磁碟快照可以指定多個，最多不能超過 16 塊。不指定DiskDeviceMapping.N.SnapshotId時會建立一個預設容量的空資料磁碟。

說明

當釋放執行個體時，系統磁碟將被轉為按量計費資料磁碟保留。該磁碟建立的快照不支援建立自訂映像，請根據需要在執行個體釋放前製作自訂映像。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

ecs:CreateImage

create

*Image

acs:ecs:{#regionId}:{#accountId}:image/*

Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

Snapshot

acs:ecs:{#regionId}:{#accountId}:snapshot/{#snapshotId}

無

請求參數

名稱	類型	必填	描述	樣本值
RegionId	string	是	映像所在的地域 ID。您可以呼叫 DescribeRegions 檢視最新的阿里雲地域清單。	cn-hangzhou
SnapshotId	string	否	用於建立自訂映像的快照 ID。說明如果僅使用執行個體的系統磁碟快照建立自訂映像時，您可以使用該參數，也可以選用參數`DiskDeviceMapping.N.SnapshotId`。如果增加資料磁碟快照，只能使用`DiskDeviceMapping.N.SnapshotId`參數指定快照。	s-bp17441ohwkdca0****
InstanceId	string	否	執行個體 ID。根據執行個體建立自訂映像時，必須指定該參數。	i-bp1g6zv0ce8oghu7****
ImageName	string	否	映像名稱。長度為 2~128 個英文或中文字元。必須以大小寫字母或中文開頭，不能以 http://和 https://開頭。可以包含數字、半形冒號（:）、底線（_）或者短橫線（-）。	TestCentOS
ImageFamily	string	否	映像族系名稱。長度為 2~128 個英文或中文字元。必須以大小寫字母或中文開頭，不能以 aliyun 和 acs:開頭，不能包含 http://或者 https://。可以包含數字、半形冒號（:）、底線（_）或者短橫線（-）。	hangzhou-daily-update
ImageVersion	string	否	映像版本。說明當您指定了執行個體 ID（`InstanceId`），並且該執行個體的映像是雲端市場映像或者來自雲端市場映像建立的自訂映像時，該參數必須和目前執行個體映像的`ImageVersion`相同或置為空。	2017011017
Description	string	否	映像的描述資訊。長度為 2~256 個英文或中文字元，不能以 http://或 https://開頭。	ImageTestDescription
Platform	string	否	作業系統，指定資料磁碟快照做映像的系統磁碟後，需要透過 Platform 確定系統磁碟的作業系統發行版。取值範圍： Aliyun Anolis CentOS Ubuntu CoreOS SUSE Debian OpenSUSE FreeBSD RedHat Kylin UOS Fedora Fedora CoreOS CentOS Stream AlmaLinux Rocky Linux Gentoo Customized Linux Others Linux Windows Server 2022 Windows Server 2019 Windows Server 2016 Windows Server 2012 Windows Server 2008 Windows Server 2003 預設值：Others Linux。	CentOS
BootMode	string	否	修改映像的啟動模式。取值範圍： BIOS：BIOS 啟動模式。 UEFI：UEFI 啟動模式。 UEFI-Preferred：雙啟動模式。重要為了避免使用映像不支援的啟動模式導致執行個體無法正常啟動，請您務必在選擇該參數之前瞭解目標映像支援的啟動模式。映像啟動模式詳情，請參閱映像啟動模式。枚舉值： BIOS : BIOS UEFI : UEFI UEFI-Preferred : UEFI-Preferred	BIOS
Architecture	string	否	系統架構，指定資料磁碟快照做映像的系統磁碟後，需要透過 Architecture 確定系統磁碟的系統架構。取值範圍： i386。 x86_64。 arm64。預設值：x86_64。	x86_64
ClientToken	string	否	保證請求冪等性。從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 只支援 ASCII 字元，且不能超過 64 個字元。更多資訊，請參閱如何保證冪等性。	123e4567-e89b-12d3-a456-426655440000
ResourceGroupId	string	否	自訂映像所在的資源群組 ID。如果不設定該參數值，建立的映像屬於預設資源群組。說明如果您使用 RAM 使用者呼叫該介面，且`ResourceGroupId`取值為空，您需要注意，當 RAM 使用者沒有預設資源群組權限時，呼叫介面會傳回錯誤訊息`Forbidden: User not authorized to operate on the specified resource`。請設定 RAM 使用者支援的資源群組 ID 或者透過相應阿里雲帳號為該 RAM 使用者授予預設資源群組權限後，再次呼叫該介面。	rg-bp67acfmxazb4p****
DiskDeviceMapping	array<object>	否	建立自訂映像使用的雲端硬碟和快照資訊集合。如果需要根據系統磁碟快照和資料磁碟快照建立自訂映像，請使用該參數指定快照。
	object	否	建立自訂映像使用的雲端硬碟和快照。
Device	string	否	指定在自訂映像中的裝置名稱。取值範圍：系統磁碟的裝置名稱必須為：/dev/xvda。資料磁碟裝置名稱從/dev/xvdb 依序排序到/dev/xvdz，不能重複。	/dev/xvdb
DiskType	string	否	指定在新映像中的雲端硬碟類型。您可以透過該參數使用資料磁碟快照作為映像的系統磁碟，如果不指定，預設為快照對應的雲端硬碟類型。取值範圍： system：系統磁碟。只能指定 1 個系統磁碟快照。 data：資料磁碟。最多可以指定 16 個資料磁碟快照。	system
Size	integer	否	雲端硬碟的大小，單位為 GiB。DiskDeviceMapping.N.Size 的取值和預設值和 DiskDeviceMapping.N.SnapshotId 有關：如果沒有指定 SnapshotId，Size 取值以及預設值為：普通雲端硬碟：5~2000GiB，預設為 5。其他雲端硬碟：20~32768GiB，預設為 20。如果指定了 SnapshotId，Size 取值必須大於或等於 SnapshotId 的大小，預設為 SnapshotId 的大小。	2000
SnapshotId	string	否	快照 ID。	s-bp17441ohwkdca0****
Tag	array<object>	否	標籤清單。
	object	否	標籤清單。
Key	string	否	映像的標籤鍵。N 的取值範圍為 1~20。一旦傳入該值，則不允許為空字串。最多支援 128 個字元，不能以`aliyun`或`acs:`開頭，不能包含`http://`或者`https://`。	KeyTest
Value	string	否	映像的標籤值。N 的取值範圍為 1~20。一旦傳入該值，允許為空字串。最多支援 128 個字元，不能以`acs:`開頭，不能包含`http://`或者`https://`。	ValueTest
key	string	否	映像的標籤鍵。說明為提高相容性，建議您盡量使用 Tag.N.Key 參數。	null
value	string	否	映像的標籤值。說明為提高相容性，建議您盡量使用 Tag.N.Value 參數。	null
DetectionStrategy	string	否	映像檢測策略，不設定此參數時不觸發檢測。僅支援標準（Standard）檢測模式。說明目前已支援大部分的 Linux/Windows 版本，關於映像檢測項目與作業系統限制說明，請參閱映像檢測概述和映像檢測作業系統限制。	Standard
Features	object	否	映像特性相關屬性。
ImdsSupport	string	否	映像的中繼資料存取模式，可能值： v1：透過該映像建立 ECS 執行個體時，不支援將中繼資料存取模式設定為「僅強化模式」。 v2：透過該映像建立 ECS 執行個體時，支援將中繼資料存取模式設定為「僅強化模式」。預設值：當使用快照建立映像時，預設為 v1。當使用執行個體建立映像時，預設取執行個體建立時映像的 ImdsSupport 屬性值。	v2
DryRun	boolean	否
SecureBootOptions	object	否	安全啟動相關參數。
SecureBootSupport	string	否	映像是否支援安全啟動。可能值： supported：支援安全啟動。 unsupported：不支援安全啟動。說明 Secure Boot 僅支援 UEFI 或 UEFI-Preferred 啟動模式。

返回參數

名稱	類型	描述	樣本值
	object
ImageId	string	映像 ID。	m-bp146shijn7hujku****
RequestId	string	請求 ID。	C8B26B44-0189-443E-9816-*******

樣本

正常返回樣本

JSON格式

{
  "ImageId": "m-bp146shijn7hujku****",
  "RequestId": "C8B26B44-0189-443E-9816-*******"
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊	描述
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	映像名稱不合法。限制條件請參見 DestinationImageName 參數說明。
400	InvalidImageName.Duplicated	The specified image name is already in use.	映像名稱已經重複。
400	InvalidDescription.Malformed	The specified description is wrongly formed.	指定的資源描述格式不合法。長度為 2-256 個字元，不能以 http:// 和 https:// 開頭。
400	InvalidImageVersion.Malformed	The specified ImageVersion is wrongly formed.	無效的映像版本號取值（或者您無權使用該快照）。
400	IncorrectInstanceStatus	The current status of the instance does not support this operation.	目前執行個體狀態不支援此類操作。
400	InstanceLockedForSecurity	The specified operation is denied as your instance is locked for security reasons.
400	InvalidDevice.Malformed	The specified parameter DiskDeviceMapping.n.Device is not valid.	指定的磁碟裝置名稱不存在。
400	MissingParameter	The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied.	參數遺失。
400	InvalidSize.ValueNotSupported	The specified parameter DiskDeviceMapping.n.Size beyond the permitted range.	指定的參數 DiskDeviceMapping.n.Size 超出取值範圍。
400	InvalidDevice.InUse	The specified parameter DiskDeviceMapping.n.Device has been occupied.	指定的裝置已經掛載了磁碟。
400	OperationDenied	The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot.	指定的快照不允許建立資料磁碟。
400	InvalidDiskCategory.CreateImage	The specified diskCategory is not allowed to create image.	指定的磁碟類型不允許建立映像。
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	參數 Architecture 格式錯誤。
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	指定的映像作業系統發行版不合法。
400	InvalidParameter.AllEmpty	%s
400	InvalidParameter.DiskType	The specified disk type which has kms key can't convert to system disk.
400	Duplicate.TagKey	The Tag.N.Key contain duplicate key.	標籤中存在重複的鍵，請保持鍵的唯一性。
400	InvalidTagKey.Malformed	The specified Tag.n.Key is not valid.	指定的標籤鍵參數有誤。
400	InvalidTagValue.Malformed	The specified Tag.n.Value is not valid.	指定的標籤值參數有誤。
400	InvalidInstance.NotFoundSystemDisk	The specified instance does not have system disk.
400	InvalidImageFamily.Malformed	The format of the specified image family is invalid.	指定的映像族系格式有誤。
400	ImageQuotaExceed.ImageFamily	The specified image family exceeds the maximum number of images for one image family.
400	ImageFamilyQuotaExceed	The number of image families exceeds the limit in the region.
400	InvalidDiskType.ValueNotSupported	The specified disk type is not supported.	指定的磁碟屬性不支援。
400	IdempotenceParamNotMatch	Request uses a client token in a previous request but is not identical to that request.	與相同 ClientToken 的請求參數不符。
400	InvalidBootMode.NotSupport	The specified parameter BootMode is not supported for current image architecture.	目前的映像架構不支援設定該啟動模式。
400	InvalidParameter.FeaturesImdsSupport	The specified parameter Features.ImdsSupport is not supported.	指定的參數 Features.ImdsSupport 不支援。
400	InvalidOperation.DiskCategoryUnsupported	The current category of the disk does not support this operation.	彈性臨時磁碟不支援單獨卸載。
400	AccountForbidden.CreateOrder	Order cannot be created due to abnormal account.	目前帳號不允許建立訂單。
400	InvalidBootMode.Malformed	The specified parameter BootMode is invalid. Valid options are BIOS, UEFI, and UEFI-Preferred.	指定的參數「BootMode」不合法。
400	InvalidDetectionStrategy.Malformed	The specified value for parameter DetectionStrategy is not supported. Please refer to the documentation for accepted values.	不支援指定的 DetectionStrategy 參數值。請參考文件了解可接受的值。
400	InvalidParameter.SecureBootSupport	The specified parameter SecureBootOptions.SecureBootSupport is not valid.	指定的參數 SecureBootOptions.SecureBootSupport 不合法。
500	InternalError	The process of creating snapshot has failed due to some unknown error.	內部錯誤，請重試。
403	IncorrectDiskStatus.NeverAttached	The specified disk has never been attached to instance.
403	InvalidSnapshotId.NotReady	The current status of the DiskDeviceMapping.n.SnapshotId or SnapshotId does not support this operation.	指定的快照未完成。
403	InvalidSnapshot.TooOld	This operation is denied because the specified snapshot by DiskDeviceMapping.n.SnapshotId or SnapshotId is created before 2013-07-15.	指定磁碟的來源快照建立於2013年7月15日（含）之前，無法重新初始化。
403	OperationDenied	The specified snapshot is not allowed to create image.	指定的快照不允許建立資料磁碟。
403	QuotaExceed.Image	The Image Quota exceeds.
403	InvalidParamter.Conflict	The specified same token is trying to make requests with different parameters.	授權與被授權安全性群組必須不同。
403	InvalidAccountStatus.NotEnoughBalance	Your account does not have enough balance.
403	InvalidAccountStatus.SnapshotServiceUnavailable	Snapshot service has not been opened yet.	快照服務未開通，操作無法執行。
403	UserNotInTheWhiteList	The user is not in the white list of create image by data disk snapshot.	使用者不在共用區塊儲存白名單中，請您提交工單申請白名單。
403	IncorrectDiskStatus.Invalid	Device status is invalid, please restart instance and try again.	目前磁碟的狀態無效，請重新啟動執行個體後重試。
403	OperationDenied.InvalidSnapshotCategory	%s	該快照類型不支援此操作。
403	QuotaExceed.Snapshot	The snapshot quota exceeds.
403	IncorrectDiskStatus.Transferring	The specified device is transferring, you can retry after the process is finished.	指定磁碟正在遷移中，請在遷移完畢後重試。
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	InvalidSystemSnapshot.Missing	%s
403	IncorrectDiskStatus.CreatingSnapshot	A previous snapshot creation is in process.
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK needs to be added ECS tag.	CMK 需要新增 ECS 標籤。
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	The ECS service is not authorized to access your KMS key. Please grant the ECS service permission to use the key and try again.
403	QuotaExceed.Tags	%s	標籤數超過可以設定的最大數量。%s 為變數，將根據呼叫 API 的實際情況動態返回錯誤訊息。
403	InvalidSnapshotCategory.NotSupportImageCreation	The specified snapshot category does not support create image.
403	TooManySnapshot.Unfinished	There are too many snapshots being created, please wait for them to be created done.
403	HibernationConfigured.InstanceOperationForbidden	The operation is not permitted due to limit of the hibernation configured instance.	不符合開啟休眠選項的執行個體的相關限制，操作不被允許。
403	SnapshotNotReady	The specified snapshot is not ready.	快照尚未完成建立，無法用來建立映像。
403	IncorrectInstanceStatus.NeedRestart	The instance needs to be restarted after adding a disk in a shutdown status.	在關機狀態下新增雲端硬碟後需要重新啟動執行個體後才能建立自訂映像。
403	QuotaExceed.ConcurrentSnapshotQuota	The number of snapshots being created for the disk %s has exceeded the concurrent quota (%s). Please wait for the previous snapshots to complete before trying again.	該磁碟正在建立的快照數量已超過並行配額，請等待之前的快照完成後再重試。
403	InvalidOperation.SnapshotStorageLocationUnsupported	Snapshots with storage location in CloudBox do not support the current operation.	儲存位置在 CloudBox 中的快照不支援目前操作。
403	AccountEnterpriseStatusInvalid	Your enterprise registration is marked as revoked/deregistered in the National Enterprise Credit Information Publicity System. Account transaction features (purchase/renewal/recharge) are disabled. Please update real-name certification via Account Center. Restrictions will auto-remove after verification.	您企業的登記狀態在國家企業信用資訊公示系統內查詢已是註銷（或吊銷）狀態，您的帳號將無法進行產品新購、續費、儲值等交易操作。請您儘快透過帳號中心變更實名認證。變更完成後，阿里雲會自動解除限購處置。
403	InvalidOperation.DefaultFreeSnapshotNotSupport	The specified snapshot is a default free snapshot and does not support this operation.	指定的快照是一個預設免費快照，不支援目前操作。
403	InvalidBootMode.SecureBootUnsupported	Secure Boot requires UEFI or UEFI-Preferred boot mode. Please check the BootMode and try again.	指定的 BootMode 參數無效，該啟動模式不支援安全啟動。
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.
404	InvalidInstanceId.NotFound	The specified instance %s does not exist.	指定的執行個體不存在，請您檢查執行個體 ID 是否正確。
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	資源群組並不在記錄中。

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。