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	否	建立自訂鏡像使用的雲端硬碟和快照。
SnapshotId	string	否	快照 ID。	s-bp17441ohwkdca0****
Size	integer	否	雲端硬碟的大小，單位為 GiB。DiskDeviceMapping.N.Size 的取值和預設值和 DiskDeviceMapping.N.SnapshotId 有關：如果沒有指定 SnapshotId，Size 取值以及預設值為：普通雲端硬碟：5~2000GiB，預設為 5。其他雲端硬碟：20~32768GiB，預設為 20。如果指定了 SnapshotId，Size 取值必須大於等於 SnapshotId 的大小，預設為 SnapshotId 的大小。	2000
Device	string	否	指定在自訂鏡像中的裝置名稱。取值範圍：系統硬碟的裝置名稱必須為：/dev/xvda。資料盤裝置名稱從/dev/xvdb 依次排序到/dev/xvdz，不能重複。	/dev/xvdb
DiskType	string	否	指定在新鏡像中的雲端硬碟類型。您可以通過該參數使用資料盤快照作為鏡像的系統硬碟，如果不指定，預設為快照對應的雲端硬碟類型。取值範圍： system：系統硬碟。只能指定 1 塊系統硬碟快照。 data：資料盤。最多可以指定 16 塊資料盤快照。	system
Tag	array<object>	否	標籤列表。
	object	否	標籤列表。
key	string	否	鏡像的標籤鍵。說明為提高相容性，建議您盡量使用 Tag.N.Key 參數。	null
Key	string	否	鏡像的標籤鍵。N 的取值範圍為 1~20。一旦傳入該值，則不允許為空白字串。最多支援 128 個字元，不能以`aliyun`或`acs:`開頭，不能包含`http://`或者`https://`。	KeyTest
Value	string	否	鏡像的標籤值。N 的取值範圍為 1~20。一旦傳入該值，允許為空白字串。最多支援 128 個字元，不能以`acs:`開頭，不能包含`http://`或者`https://`。	ValueTest
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	否

返回參數

名稱	類型	描述	樣本值
	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.	鏡像名稱格式錯誤。長度為2~128個字元。必須以大小字母或中文開頭，不能以aliyun和acs:開頭，不能包含http://或者https://。可以包含數字、半形句號（.）、半形冒號（:）、底線（_）或者短劃線（-）。
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.	指定的參數 DiskDeviceMapping.n.Device 不合法。
400	MissingParameter	The input parameter SnapshotId or InstanceId or DiskDeviceMapping that is mandatory for processing this request is not supplied.	參數 SnapshotId，InstanceId 和 DiskDeviceMapping 不得為空白。
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.	指定的參數 DiskDeviceMapping.n.Device 已被佔用。
400	OperationDenied	The specified parameter DiskDeviceMapping.n.SnapshotId does not contain system disk snapshot.	系統硬碟快照中不存在指定的 DiskDeviceMapping 快照 ID。
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參數無效。有效選項包括BIOS、UEFI和UEFI- preferred。
400	InvalidDetectionStrategy.Malformed	The specified value for parameter DetectionStrategy is not supported. Please refer to the documentation for accepted values.	不支援指定的DetectionStrategy參數值。請參考文檔瞭解可接受的值。
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.	該操作被拒絕。因為 DiskDeviceMapping.n.SnapshotId 或 SnapshotId 指定的快照建立於 2013-07-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.	同一個 Token 正在請求處理兩個不同的參數。
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 未授權
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK needs to be enabled.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service have no right to access your KMS.	ECS 服務無權訪問您的 KMS。
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.	指定的快照是一個預設免費快照，不支援當前操作。
404	InvalidSnapshotId.NotFound	The specified SnapshotId does not exist.
404	InvalidInstanceId.NotFound	The specified instance %s does not exist.	指定的執行個體不存在。
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	資源群組並不在記錄中。

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

變更歷史

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