全部产品
Search
文档中心

云服务器 ECS:ExportImage - 导出一份自定义镜像到OSS

更新时间:Aug 27, 2026

导出一份自定义镜像到与自定义镜像同一地域的OSS Bucket里。

接口说明

导出镜像前:

  • 您需要先了解前提条件以及注意事项。更多信息,请参见导出镜像

  • 设置参数ImageFormat镜像导出格式功能仅在部分地域可用,支持的地域有日本(东京)、印度尼西亚(雅加达)、德国(法兰克福)、阿联酋(迪拜)、美国(弗吉尼亚)、英国(伦敦)、新加坡、马来西亚(吉隆坡)和美国(硅谷)。不支持设置镜像格式的地域,默认导出 RAW 格式的镜像。

  • 您必须通过 RAM 授权云服务器 ECS 写入 OSS 的权限。具体操作说明如下:

    • 创建角色:AliyunECSImageExportDefaultRole(其他任何角色名称无效),为该角色设置以下角色策略:

         {
           "Statement": [
             {
               "Action": "sts:AssumeRole",
               "Effect": "Allow",
               "Principal": {
                 "Service": [
                   "ecs.aliyuncs.com"
                 ]
               }
             }
           ],
           "Version": "1"
         }
      

    • 在角色AliyunECSImageExportDefaultRole下加入默认的系统权限策略:AliyunECSImageExportRolePolicy,该策略是云服务器 ECS 提供导出镜像的默认策略。更多详情,请参见云资源访问授权。您也可以创建自定义策略,权限需要包含:

           {
             "Version": "1",
             "Statement": [
               {
                 "Action": [
                   "oss:GetObject",
                   "oss:PutObject",
                   "oss:DeleteObject",
                   "oss:GetBucketLocation",
                   "oss:GetBucketInfo",
                   "oss:AbortMultipartUpload",
                   "oss:ListMultipartUploads",
                   "oss:ListParts"
                 ],
                 "Resource": "*",
                 "Effect": "Allow"
               }
             ]
           }
      

导出镜像后:

自定义镜像将保存在指定的 OSS bucket 中,您可以下载自定义镜像。具体操作,请参见下载自定义镜像文件

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。

  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。

  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:

    • 对于必选的资源类型,用前面加 * 表示。

    • 对于不支持资源级授权的操作,用全部资源表示。

  • 条件关键字:是指云产品自身定义的条件关键字。

  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ecs:ExportImage

update

*Image

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

请求参数

名称

类型

必填

描述

示例值

RegionId

string

自定义镜像的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。

cn-hangzhou

ImageId

string

自定义镜像 ID。

m-bp67acfmxazb4p****

OSSBucket

string

保存导出镜像的 OSS bucket。

testexportImage

OSSPrefix

string

您的 OSS Object 的前缀。可以由数字或者字母组成,字符长度为 1~30。

EcsExport

ImageFormat

string

镜像文件的导出格式。取值范围:

  • raw。

  • vhd。

  • qcow2。

  • vmdk。

  • vdi。

默认值:raw。

raw

RoleName

string

导出镜像时使用的 RAM 角色名称。

AliyunECSImageExportDefaultRole

DryRun

boolean

返回参数

名称

类型

描述

示例值

object

RequestId

string

请求 ID。

C8B26B44-0189-443E-9816-D951F596****

TaskId

string

导出镜像任务 ID。

tsk-bp67acfmxazb4p****

RegionId

string

地域 ID。

cn-hangzhou

示例

正常返回示例

JSON格式

{
  "RequestId": "C8B26B44-0189-443E-9816-D951F596****",
  "TaskId": "tsk-bp67acfmxazb4p****",
  "RegionId": "cn-hangzhou"
}

错误码

HTTP status code

错误码

错误信息

描述

400 MissingParameter An input parameter "RegionId" that is mandatory for processing the request is not supplied.
400 InvalidImageName.Malformed The specified Image name is wrongly formed. 镜像名称格式错误。长度为2~128个字符。必须以大小字母或中文开头,不能以aliyun和acs:开头,不能包含http://或者https://。可以包含数字、半角句号(.)、半角冒号(:)、下划线(_)或者短划线(-)。
400 InvalidOSSPrefix.Malformed The specified OSSPrefix format is wrongly formed. 参数 OssPrefix 格式错误。
400 InvalidRegionId.NotFound The specified RegionId does not exist.
400 InvalidRegion.NotSupport The specified region does not support image import or export. 指定的地域暂时不支持此操作。
400 IncorrectImageStatus The specified Image is not available. 指定的源镜像状态不正确。
400 InvalidImageFormat.Malformed The specified Image Format is wrongly formed. 指定的镜像格式错误。
400 InvalidOSSBucket.NotFound The specified OSS bucket does not exist in this region. 指定的 bucket 不存在。
400 OperationDenied The specified image contains the snapshot of the data disk,does not support this operation. 包含了数据盘快照的镜像,不支持此操作。
400 InvalidImage.DiskAmountOrSize %s 无效的镜像,导出的镜像限制数据盘数不能超过 4 块,单块数据盘容量最大不能超过 500 GiB。
400 ImageNotSupported The specified Image contains encrypted snapshots, do not support export. 指定的镜像包含了加密快照,不支持导出。
400 InvalidOSSObject.NeedRestore The specified OSS object is a archive object, need restore first.
400 InvalidOSSBucket.NotMatched The specified OSS bucket is incorrect, %s. 指定的 OSS Bucket 有误,具体信息请参见错误信息的实际返回结果。
400 InvalidImageFormat.RegionNotSupported The specified image format is not supported in current region.
400 InvalidOSSBucket.ArchiveOssBucketNotSupported Exporting an image to an OSS bucket with Archive, Cold Archive, or Deep Cold Archive storage class is not supported. 不支持将镜像导出到存储类型为归档存储、冷归档存储或深度冷归档存储的OSSBucket中。
403 ImageNotSupported The specified image from the image market, do not support export image. 指定的镜像来自云市场镜像,此镜像不能导出。
403 ImageIsExporting The specified Image is being exported. You can use the DescribeTasks API to check the status of existing tasks. 指定的镜像正在被导出。您可以使用DescribeTasks API查询进行中的任务状态。
403 ExportImageFailed Exporting image is failed, Please contact the administrator. 导出镜像失败,请联系系统管理员。
403 UserNotInTheWhiteList The user is not in the white list of exporting image. 该用户不在导出镜像白名单中。
403 NoSetRoletoECSServiceAcount ECS service account Have no right to access your OSS.please attach a role of access your oss to ECS service account.
403 InvalidOSS.NotAuthorized The specified OSS bucket or object is not allowed to access. 您没有权限访问指定的OSS的bucket和Object。
403 ConcurrentQuotaExceed.ExportImage %s
403 WeeklyQuotaExceed.ExportImage %s
403 InvalidImageLicense.NotSupported %s 指定的镜像不支持导出。具体信息请参见错误信息%s占位符的实际返回值。
403 InvalidImageCategory.NotSupported The specified image category is not supported. 指定镜像的镜像所属类型(ImageCategory或更通用称为ImageOwnerAlias)不支持此操作。
403 InvalidOSSBucket.EncryptUnsupported Accessing objects from encrypted OSS bucket is not supported. 不支持从加密的OSS bucket读取对象。
404 InvalidImageId.NotFound The specified ImageId does not exist. 指定的镜像在该用户账号下不存在,请您检查镜像 ID 是否正确。

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

变更历史

更多信息,参考变更详情