使用CopyImage跨地域复制自定义镜像-云服务器 ECS-阿里云-云服务器 ECS(ECS)-阿里云帮助中心

复制一个地域下的自定义镜像到其他地域。复制镜像可以实现跨地域部署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	否	标签列表。
Value	string	否	复制后的镜像的标签值。N 的取值范围为 1~20。一旦传入该值，可以为空字符串。最多支持 128 个字符，不能以`acs:`开头，不能包含`http://`或`https://`。	TestValue
Key	string	否	复制后的镜像的标签键。N 的取值范围为 1~20。一旦传入该值，则不允许为空字符串。最多支持 128 个字符，不能以`aliyun`或`acs:`开头，不能包含`http://`或`https://`。	TestKey
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"
}

异常返回示例

JSON格式

{
    "RequestId": "C8B26B44-0189-443E-9816-D951F59623A9",
    "ImageId": "Img-231234567"
}

错误码

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 specified parameter Encrypted must be true when kmsKeyId is not empty.	设置参数 KMSKeyId 后，您必须开启加密属性。
400	InvalidEncrypted.NotMatchEncryptAlgorithm	The specified parameter Encrypted must be true when EncryptAlgorithm is not empty.
400	InvalidEncryptAlgorithm	The specified parameter EncryptAlgorithm is not valid.
400	InvalidEncrypted.NotMatchKmsKeyId	The specified parameter Encrypted must be true when KmsKeyId is not empty.
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-07-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	ECS service have no right to access your KMS.	ECS 服务无权访问您的 KMS。
403	InvalidRegion.NotSupport	The specified region does not support byok.	该地域不支持BYOK。
403	UserNotInTheWhiteList	The user is not in byok white list.	您不在byok白名单中，请加入白名单后重试。
403	InvalidRegionId.NotSupportEncryptAlgorithm	The current region does not support creating encrypted disks with EncryptAlgorithm.
403	OperationDenied.KmsServiceUnauthorized	The account is not authorized to kms service, please authorize it.	用户未授权kms服务，请先授权。
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	Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support.	使用KMS主密钥创建数据密钥失败，请联系KMS值班同学进一步排查。
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.	镜像的大小已超过可操作的最大值。您可以使用CopySnapshot接口复制这个镜像的快照到目标地域，然后用复制后快照创建一个新的镜像。
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK (Customer Master Key) must be in an active state.	用户主密钥（CMK）需要处于活动状态。
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.	用户主密钥（CMK）未授权ECS服务添加标签权限。
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.	指定的参数 KMSKeyId 不存在。
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.	请求操作的资源与之前的请求冲突

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。