全部產品
Search

搜尋本產品

    Elastic Compute Service：CopyImage

    文件中心

    Elastic Compute Service：CopyImage

    更新時間：Sep 15, 2026

    複製一個地域下的自訂映像到其他地域。複製映像可以實現跨地域部署ECS執行個體、跨地域複製ECS執行個體等目的。

    介面說明

    介面說明

    您可以在其他地域使用複製後的映像建立 ECS 執行個體（RunInstances），或者更換執行個體的系統磁碟（ReplaceSystemDisk）。

    呼叫該介面時，您需要注意：

    • 自訂映像的狀態必須為可用（Available）。

    • 映像是您帳號下的自訂映像時，可以跨地域複製映像；映像是其他人共享給您的映像時，只能同地域複製映像。

    • 複製映像期間，您無法直接操作刪除（ DeleteImage ）複製中的映像，但是您可以透過取消複製任務（ CancelCopyImage ）的方式來刪除複製中的映像。

    • 同一個地域下同時只能有五個映像複製任務執行，其餘任務需要排隊等待上述任一任務完成後再依次排隊執行。

    • 您可以透過ResourceGroupId參數指定複製後的映像所屬的資源群組。如果不設定ResourceGroupId參數值，複製後的映像屬於預設資源群組。

    調試

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

    調試

    授權資訊

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

    • 操作：是指具體的許可權點。

    • 存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。

    • 資源類型：是指操作中支援授權的資源類型。具體說明如下：

      • 對於必選的資源類型，用前面加 * 表示。

      • 對於不支援資源級授權的操作，用全部資源表示。

    • 條件關鍵字：是指雲產品自身定義的條件關鍵字。

    • 關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

    操作

    存取層級

    資源類型

    條件關鍵字

    關聯操作

    ecs:CopyImage

    update

    *Image

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

    		 無 無

    請求參數

    名稱

    類型

    必填

    描述

    樣本值
    DestinationImageName

    string

    否

    複製後的映像的名稱。長度為 2~128 個字元。必須以大小寫字母或中文開頭，也不能以aliyun或acs:開頭，不能包含http://或者https://。可以包含數字、半形句號（.）、半形冒號（:）、底線（_）或者短橫線（-）。

    YourImageName
    DestinationDescription

    string

    否

    複製後的映像的描述資訊。長度為 2~256 個英文或中文字元，不能以http://或https://開頭。

    This is a description example.
    ImageId

    string

    是

    來源自訂映像的 ID。

    m-bp1h46wfpjsjastc****
    RegionId

    string

    是

    來源自訂映像的地域 ID。您可以呼叫 DescribeRegions 查看最新的阿里雲地域清單。

    cn-hangzhou
    DestinationRegionId

    string

    否

    複製到目標地域的 ID。

    cn-shanghai
    Encrypted

    boolean

    否

    是否加密複製後的映像。

    • true：加密。

    • false：不加密。

    • 不指定：需要依賴後端判斷，判斷邏輯見下文的補充說明。

    預設值：不指定。

    false
    KMSKeyId

    string

    否

    加密映像使用的金鑰 ID。

    e522b26d-abf6-4e0d-b5da-04b7******3c
    EncryptAlgorithm

    string

    否

    說明

    該參數暫未開放使用。

    hide
    ResourceGroupId

    string

    否

    複製後的映像的資源群組 ID。如果不設定該參數值，複製後的映像屬於預設資源群組。

    說明

    如果您目前使用的是 RAM 使用者呼叫該介面，且ResourceGroupId取值為空，您需要注意，當 RAM 使用者沒有預設資源群組權限時，呼叫介面會返回錯誤資訊Forbidden: User not authorized to operate on the specified resource。請您設定 RAM 使用者支援的資源群組 ID 或者透過相應阿里雲帳號為該 RAM 使用者授予預設資源群組權限後，再次呼叫該介面。

    rg-bp67acfmxazb4p****
    Tag

    array<object>

    否

    標籤清單。

    object

    否

    標籤清單。

    Key

    string

    否

    複製後的映像的標籤鍵。N 的取值範圍為 1~20。一旦傳入該值，則不允許為空字串。最多支援 128 個字元，不能以aliyun或acs:開頭，不能包含http://或https://。

    TestKey
    Value

    string

    否

    複製後的映像的標籤值。N 的取值範圍為 1~20。一旦傳入該值，可以為空字串。最多支援 128 個字元，不能以acs:開頭，不能包含http://或https://。

    TestValue
    DryRun

    boolean

    否

    是否只預檢此次請求。取值範圍：

    • true：傳送預檢請求。檢查項目包括 AccessKey 是否有效、RAM 使用者的授權情況和是否填寫了必需參數等。如果檢查不通過，則返回對應錯誤資訊。如果檢查通過，則返回錯誤碼DryRunOperation。

    • false：傳送正常請求，通過檢查後返回 2XX HTTP 狀態碼並直接操作資源。

    預設值：false。

    false
    ClientToken

    string

    否

    保證請求冪等性。從您的用戶端產生一個參數值，確保不同請求間該參數值唯一。ClientToken 只支援 ASCII 字元，且不能超過 64 個字元。更多資訊，請參見如何保證冪等性。

    123e4567-e89b-12d3-a456-426655440000
    場景來源映像狀態Encrypted 參數KMSKeyId 參數目標地域是否設定區塊儲存帳號級加密目標映像結果結果說明
    1非加密映像False 或未指定未指定未設定非加密映像不加密，映像保持原樣。
    2非加密映像True未指定任意全加密映像使用者明確要求加密。如果已經設定了區塊儲存帳號級加密，則選擇設定的預設金鑰加密。否則使用服務金鑰加密。
    3非加密映像True指定任意全加密映像使用者明確要求加密。使用使用者指定的 KMSKeyId 加密。
    4非加密映像未指定未指定已設定全加密映像使用區塊儲存帳號級加密設定的金鑰加密。
    5加密映像未指定未指定未設定加密映像保持原有的格式，不加密的快照不加密，加密的按照服務金鑰加密。
    6加密映像未指定或 True未指定已設定全加密映像使用區塊儲存帳號級加密設定的金鑰加密。
    7加密映像True未指定未設定全加密映像使用服務金鑰加密。
    8加密映像True未指定已設定全加密映像使用區塊儲存帳號級加密設定的金鑰加密。
    9加密映像True指定任意全加密映像使用者明確要求加密。使用使用者指定的 KMSKeyId 加密。

    返回參數

    名稱

    類型

    描述

    樣本值

    object

    ImageId

    string

    複製後的映像的 ID。

    m-bp1h46wfpjsjastd****
    RequestId

    string

    請求 ID。

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    樣本

    正常返回樣本

    JSON格式

    {
  "ImageId": "m-bp1h46wfpjsjastd****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

    錯誤碼

    HTTP status code

    錯誤碼

    錯誤資訊

    描述
    400 InvalidDescription.Malformed The specified destination description is wrongly formed. 指定的資源描述格式不合法。長度為 2-256 個字元，不能以 http:// 和 https:// 開頭。
    400 SourceRegion.NotFound The source region not found.
    400 DestinationRegion.NotFound The destination region not found. 指定的目標地域不存在。
    400 IncorrectImageStatus The image not available. 複製映像失敗。
    400 InvalidSnapshotId.NotFound The specified SnapshotId does not exist. 指定的快照不存在，請您檢查快照是否正確。
    400 InvalidImageName.Duplicated The specified image name is already in use in the target region. Please try a different one. 映像名稱已經重複。
    400 InvalidParameter.EncryptedIllegal The Encrypted parameter must be set to true when KMSKeyId is specified. Please adjust the parameters and try again.
    400 InvalidEncrypted.NotMatchEncryptAlgorithm The Encrypted parameter must be set to true when EncryptAlgorithm is specified. Please adjust the parameters and try again.
    400 InvalidEncryptAlgorithm The specified EncryptAlgorithm is not valid. Ensure the value is a supported encryption algorithm such as AES-256.
    400 InvalidEncrypted.NotMatchKmsKeyId The Encrypted parameter must be set to true when KMSKeyId is specified. Please adjust the parameters and try again.
    400 OperationDenied.CommunityImage Community image does not support copy. 社群映像不支援複製。
    400 InvalidImageName.Malformed The specified destination image name is wrongly formed. 映像名稱不合法。限制條件請參見 DestinationImageName 參數說明。
    400 InvalidParameter.KmsNotEnabled The specified operation need enable KMS. 目前操作需要啟用 KMS。
    400 OperationDenied.ImageCopyConflict The same image cannot be copied concurrently. Please wait until the last copy is completed before performing the next operation. 同一映像無法並行複製，請等待上一次複製完成後再進行下一次操作。
    400 Account.Arrearage Your account has an outstanding payment. 帳戶餘額不足，請先儲值再操作。
    400 Duplicate.TagKey The Tag.N.Key contain duplicate key. 標籤中存在重複的鍵，請保持鍵的唯一性。
    401 InvalidAliUid.IsNull The aliUid must not be null.
    500 InternalError The request processing has failed due to some unknown error, exception or failure. 內部錯誤，請重試。
    403 Forbbiden User not authorized to operate on the specified resource. 使用者未被授權操作指定的資源。
    403 InvalidOperation.CopyingDataFromThisRegionUnsupported Data transfer from the current region to other regions is not supported. 不支援從目前地域複製資料到其他地域。
    403 InvalidOperation.CopyingDataToThisRegionUnsupported Only Some Regions %s can copy data to this region. 只有某些地域可以複製資料到目前地域。
    403 QuotaExceed.Image The number of images exceeds the limit (%s). 自訂映像配額已用完。
    403 QuotaExceed.Snapshot The snapshot quota exceeds.
    403 OperationDenied.ImageCopying The image is currently being copied. Please try again later. 正在複製映像，請您稍後再試。
    403 RegionNotSupportCopy The region not support copy.
    403 InvalidSnapshot.TooOld This operation is denied because the specified snapshot is created before 2013-07-15. 指定磁碟的來源快照建立於2013年7月15日（含）之前，無法重新初始化。
    403 OperationDenied The specified snapshot is not allowed to create image. 指定的快照不允許建立資料磁碟。
    403 IncorrectDestinationRegion The destination region is not equal the target region.
    403 OperationDeined.EncryptedSnapshot The image contains encrypted snapshots, which do not support copying. 該映像包含加密快照。
    403 OperationDenied.SameRegionOnly The image shared from others can not be copied to another region directly. 其他人分享的映像不能複製到另一個地域。
    403 OperationDenied.NotPublished The operation is denied because corresponding marketplace image is not published in destination region. 指定的操作無法執行，映像的原始映像來自雲端市場，並且未在目標地域發佈。
    403 OperationDenied.NotAuthorized The operation is denied because corresponding marketplace image is not authorized to current user.
    403 OperationDenied.EncryptSnapshotAcrossRegion The image do not contain encrypted snapshots, which do not support copying to encrypted ones.
    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 InvalidRegion.NotSupport The specified region does not support byok. 不支援指定的地域。
    403 UserNotInTheWhiteList The user is not in byok white list. 使用者不在共用區塊儲存白名單中，請您提交工單申請白名單。
    403 InvalidRegionId.NotSupportEncryptAlgorithm The current region does not support creating encrypted disks with EncryptAlgorithm.
    403 OperationDenied.KmsServiceUnauthorized 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 OperationDenied.NonCompliantDestinationRegion The copy operation to the destination region is not in compliance with regulations. 目標地域不符合安全合規要求。
    403 InvalidEncrypted.NotMatchDiskDefaultEncryption The specified parameter Encrypted not match for your account default encryption settings. 加密參數與目前帳號雲端硬碟預設加密設定不相符。
    403 InvalidParameter.DataEncryptedKeyCreateFailed 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 SizeExceed.Image The image exceeds the maximum size. You can use the CopySnapshot API to copy your snapshots of the image and then create a new image from them. 指定映像的大小已超過限制，請提交工單申請開放限制。
    403 InvalidParameter.KMSKeyId.CMKNotEnabled The specified KMS key must be in an enabled state. Please enable the key in the KMS console and try again.
    403 InvalidParameter.KMSKeyId.CMKUnauthorized The specified KMS key is not authorized for the ECS service. Please grant the ECS service permission to use the key in the KMS console and try again.
    403 InvalidOperation.VhdImageUnsupported The specified vhd image is not supported for this operation. Please switch to a raw image and retry. vhd 格式映像不支援此操作，請切換使用 raw 格式映像後重試。
    403 InvalidOperation.CloudBoxImageCopyUnsupported Copying CloudBox images is not supported. 雲端盒子映像不支援複製。
    403 OperationDenied.KMSKeyUnauthorized The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
    404 InvalidImageId.NotFound The specified ImageId does not exist. 指定的映像在該使用者帳號下不存在，請您檢查映像 ID 是否正確。
    404 InvalidParameter.KMSKeyId.NotFound The specified KMSKeyId does not exist. Please verify that the key ID is correct and that the key resides in the current region.
    404 InvalidResourceGroup.NotFound The ResourceGroup provided does not exist in our records. 資源群組並不在記錄中。
    409 InvalidOperation.Conflict Request was denied due to conflict with a previous request, please try again later. 由於工作衝突，不允許此操作。

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

    變更歷史

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