调用CopyImage复制一个地域下的自定义镜像到其他地域。复制镜像可以实现跨地域部署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 | *全部资源 * |
| 无 |
请求参数
名称 | 类型 | 必填 | 描述 | 示例值 |
---|---|---|---|---|
DestinationImageName | string | 否 | 复制后的镜像的名称。长度为 2~128 个字符。必须以大小写字母或中文开头,也不能以 | YourImageName |
DestinationDescription | string | 否 | 复制后的镜像的描述信息。长度为 2~256 个英文或中文字符,不能以 | This is a description example. |
ImageId | string | 是 | 源自定义镜像的 ID。 | m-bp1h46wfpjsjastc**** |
RegionId | string | 是 | 源自定义镜像的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。 | cn-hangzhou |
DestinationRegionId | string | 否 | 复制到目标地域的 ID。 | cn-shanghai |
Encrypted | boolean | 否 | 是否加密复制后的镜像。
默认值: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 个字符,不能以 | TestKey |
Value | string | 否 | 复制后的镜像的标签值。N 的取值范围为 1~20。一旦传入该值,可以为空字符串。最多支持 128 个字符,不能以 | TestValue |
返回参数
示例
正常返回示例
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 destination image is exist. | 指定的镜像名已存在。 |
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. | 同一镜像不能并发拷贝,请等待上一次拷贝完成再进行下一次操作。 |
401 | InvalidAliUid.IsNull | The aliUid must not be null. | - |
403 | Forbbiden | User not authorized to operate on the specified resource. | 用户未被授权操作指定的资源。 |
403 | QuotaExceed.Image | The Image Quota exceeds. | 自定义镜像额度已用完。 |
403 | QuotaExceed.Snapshot | The snapshot quota exceeds. | 快照额度超过限制,若要存储新快照,在不影响业务的情况下,请您删除已有的老快照。 |
403 | OperationDenied.ImageCopying | The Image are coping. | 正在复制镜像,请您稍后再试。 |
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 | SizeExceed.Image | The image exceeds the maximum size. Please open a ticket to add the account to the white list. | 镜像的大小已超过可操作的最大值。 |
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 | OperationDeined.EncryptedSnapshot | The image contains encrypted snapshots, which do not support copying to non-encrypted ones. | 镜像包含加密快照,不支持复制到非加密快照。 |
403 | OperationDenied.EncryptSnapshotAcrossRegion | The image do not contain encrypted snapshots, which do not support copying to encrypted ones. | - |
403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | 加密云盘设置了 KMSKeyId 后,CMK必须处于启用状态。您可以调用密钥管理服务的 DescribeKey 接口查询指定CMK的相关信息。 |
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值班同学进一步排查。 |
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. | 资源组并不在记录中。 |
500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 内部错误,请重试。 |
访问错误中心查看更多错误码。
变更历史
变更时间 | 变更内容概要 | 操作 |
---|---|---|
2024-12-09 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-09-05 | OpenAPI 错误码发生变更 | 查看变更详情 |
2024-06-27 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-12-18 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-10-09 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-08-23 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-07-12 | OpenAPI 错误码发生变更 | 查看变更详情 |
2023-03-03 | OpenAPI 错误码发生变更 | 查看变更详情 |