使用DescribeImages接口查询镜像列表-云服务器 ECS-阿里云-云服务器 ECS(ECS)-阿里云帮助中心

指定ImageId、镜像被使用场景、Filter过滤等参数，查询您可以使用的镜像资源列表。

接口说明

您可以查询的镜像资源包括您的自定义镜像、阿里云提供的公共镜像、云市场镜像以及其他阿里云用户主动共享给您的共享镜像。
支持分页查询，查询结果包括可使用的镜像资源的总数和当前页的镜像资源。每页的数量默认为 10 条。
通过阿里云 CLI 调用 API 时，不同数据类型的请求参数取值必须遵循格式要求。更多信息，请参见 CLI 参数格式说明。
当查询阿里云官方提供的镜像或共享镜像（ImageOwnerAlias 指定 system 或 others）时，本次请求可忽略 RAM 鉴权规则。更多信息，请参见鉴权规则。

调试

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

调试

授权信息

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

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ecs:DescribeImages

get

Image

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

Image

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

无

请求参数

名称	类型	必填	描述	示例值
RegionId	string	是	镜像所属的地域 ID。您可以调用 DescribeRegions 查看最新的阿里云地域列表。	cn-hangzhou
Status	string	否	查询指定状态的镜像，如果不配置此参数，默认只返回 Available 状态的镜像。取值范围： Creating：镜像正在创建中。 Waiting：多任务排队中。 Available（默认）：您可以使用的镜像。 UnAvailable：您不能使用的镜像。 CreateFailed：创建失败的镜像。 Deprecated：已弃用的镜像。默认值：Available。当前参数支持同时取多个值，值之间以半角逗号（,）隔开。	Available
ImageId	string	否	镜像 ID。镜像 ID 的命名规则公共镜像：以操作系统版本号、架构、语言和发布日期命名。例如，Windows Server 2008 R2 企业版、64 位英文系统的镜像 ID 为 win2008r2_64_ent_sp1_en-us_40G_alibase_20190318.vhd。自定义镜像、共享镜像、云市场镜像、社区镜像的镜像：以 m 开头。	m-bp1g7004ksh0oeuc****
ShowExpired	boolean	否	订阅型镜像是否已经超过使用期限。	false
SnapshotId	string	否	根据某一快照 ID 创建的自定义镜像。	s-bp17ot2q7x72ggtw****
ImageName	string	否	镜像名称。支持模糊搜索。	testImageName
ImageFamily	string	否	镜像族系名称，查询镜像时可通过设置该参数来过滤当前族系对应的镜像。默认值：空。说明阿里云官方镜像关联的镜像族系信息请参见公共镜像概述。	hangzhou-daily-update
ImageOwnerAlias	string	否	镜像来源。取值范围： system：阿里云官方提供的，且不是通过云市场发布的镜像，和控制台中的“公共镜像”概念不同。 self：您创建的自定义镜像。 others：包含共享镜像（其他阿里云用户直接共享给您的镜像）和社区镜像（任意阿里云用户将其自定义镜像完全公开共享后的镜像）。您需要注意：查找社区镜像时，IsPublic 必须为 true。查找共享镜像时，IsPublic 需要设置为 false 或者不传值。 marketplace：阿里云或者第三方供应商 ISV 在云市场发布的镜像，需要和 ECS 一起购买。请自行留意云市场镜像的收费详情。默认值：空。说明空表示返回取值为 system、self 以及 others 的结果。	self
InstanceType	string	否	为指定的实例规格查询可以使用的镜像。	ecs.g5.large
IsSupportIoOptimized	boolean	否	镜像是否可以运行在 I/O 优化实例上。	true
IsSupportCloudinit	boolean	否	镜像是否支持 cloud-init。	true
OSType	string	否	镜像的操作系统类型。取值范围： windows。 linux。	linux
Architecture	string	否	镜像的体系架构。取值范围： i386。 x86_64。 arm64。	i386
PageNumber	integer	否	镜像资源列表的页码。起始值：1。默认值：1。	1
PageSize	integer	否	分页查询时设置的每页行数。最大值：100。默认值：10。	10
Usage	string	否	镜像是否已经运行在 ECS 实例中。取值范围： instance：镜像处于运行状态，有 ECS 实例使用。 none：镜像处于闲置状态，暂无 ECS 实例使用。	instance
DryRun	boolean	否	是否只预检此次请求。 true：发送检查请求，不会查询资源状况。检查项包括 AccessKey 是否有效、RAM 用户的授权情况和是否填写了必需参数。如果检查不通过，则返回对应错误。如果检查通过，会返回错误码 DryRunOperation。 false：发送正常请求，通过检查后返回 2XX HTTP 状态码并直接查询资源状况。默认值：false。	false
ActionType	string	否	镜像需要被使用到的场景。取值范围： CreateEcs（默认）：创建实例。 ChangeOS：更换系统盘/更换操作系统。	CreateEcs
ResourceGroupId	string	否	自定义镜像所在的企业资源组 ID。使用该参数过滤资源时，资源数量不能超过 1000 个。说明不支持默认资源组过滤。	rg-bp67acfmxazb4p****
Tag	array<object>	否	标签列表。
	object	否	标签信息。
key	string	否	镜像的标签键。说明该参数即将被弃用，为提高兼容性，建议您使用另一个`Tag.N.Key`参数。	null
Key	string	否	镜像的标签键。N 的取值范围：1~20。使用一个标签过滤资源，查询到该标签下的资源数量不能超过 1000 个；使用多个标签过滤资源，查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个，请使用 ListTagResources 接口进行查询。	TestKey
Value	string	否	镜像的标签值。N 的取值范围：1~20。	TestValue
value	string	否	镜像的标签值。说明该参数即将被弃用，为提高兼容性，建议您使用另一个`Tag.N.Value`参数。	null
Filter	array<object>	否	查询资源时的筛选条件列表。
	object	否	查询资源时的筛选条件。
Key	string	否	查询资源时的筛选键。取值范围：当该参数取值为`CreationStartTime`时，可以查询在指定时间点（`Filter.N.Value`）后创建的资源信息。当该参数取值为`CreationEndTime`时，可以查询在指定时间点（`Filter.N.Value`）前创建的资源信息。当该参数取值为`NetworkType`时，可以查询指定网络类型的资源信息。当该参数取值为`CpuOnlineUpgrade`、`CpuOnlineDowngrade`、`MemoryOnlineUpgrade`、`MemoryOnlineDowngrade`中的任何一个值时，可以查询指定镜像的 CPU 或内存的热插拔支持情况。默认值：null。	CreationStartTime
Value	string	否	查询资源时的筛选值。当（`Filter.N.Key`）为`CreationStartTime`或`CreationEndTime`时，格式为：`yyyy-MM-ddTHH:mmZ`，采用 UTC+0 时区。当（`Filter.N.Key`）为`NetworkType`时，可以指定网络类型的值有：`vpc`、`classic`等。当（`Filter.N.Key`）取值为`CpuOnlineUpgrade`、`CpuOnlineDowngrade`、`MemoryOnlineUpgrade`、`MemoryOnlineDowngrade`时，该值可以取`supported`或`unsupported`。默认值：null。	2017-12-05T22:40Z
IsPublic	boolean	否	是否查询已发布的社区镜像。取值范围： true：查询已发布的社区镜像。当您指定该参数值为 true 时，ImageOwnerAlias 必须为 others。 false：查询除社区镜像的其他镜像类型，具体以 ImageOwnerAlias 参数值为准。默认值：false。	false
ImageOwnerId	integer	否	镜像所属的阿里云账号 ID。该参数仅在查询共享镜像以及社区镜像时生效。	20169351435666****

返回参数

名称	类型	描述	示例值
	object
PageSize	integer	当前分页包含多少条目。	1
PageNumber	integer	当前页码。	1
RequestId	string	请求 ID。	66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCount	integer	镜像总数。	1
RegionId	string	镜像所属地域 ID。	cn-hangzhou
Images	object
Image	array<object>	镜像信息 Images 组成的集合。
	array<object>	镜像信息。
CreationTime	string	镜像的创建时间。	2019-11-15T06:07:05Z
Status	string	镜像的状态。可能值： UnAvailable：不可用。 Available：可用。 Creating：创建中。 CreateFailed：创建失败。	Available
ImageFamily	string	镜像族系名称。	hangzhou-daily-update
Progress	string	镜像完成的进度，单位为百分比。	100%
IsCopied	boolean	是否是拷贝的镜像。	false
IsSupportIoOptimized	boolean	是否可以在 I/O 优化实例上运行。	true
ImageOwnerAlias	string	镜像来源。可能值： system：阿里云提供的公共镜像。 self：您创建的自定义镜像。 others：其他阿里云用户提供的共享镜像或社区镜像。 marketplace：云市场镜像提供的镜像。	self
IsSupportCloudinit	boolean	是否支持 Cloud Init。	true
ImageVersion	string	镜像版本。	2
Usage	string	有引用关系的资源类型。可能值： instance：创建了一台或多台 ECS 实例。 none：未创建过 ECS 实例。	none
IsSelfShared	string	是否共享过该自定义镜像给其他用户。	true
Description	string	描述信息。	Archive log for Oracle
Size	integer	镜像大小，单位：GiB。重要如果镜像包含数据盘，此参数仅代表镜像关联的系统盘快照大小。	60
ResourceGroupId	string	镜像所在的企业资源组 ID。	rg-bp67acfmxazb4p****
Platform	string	操作系统平台。	Windows Server 2016
OSNameEn	string	操作系统的英文显示名称。	Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageName	string	镜像的名称。	testImageName
OSName	string	操作系统的中文显示名称。	Windows Server 2016 数据中心版 64位中文版
ImageId	string	镜像 ID。	m-bp1g7004ksh0oeuc****
OSType	string	操作系统类型。可能值： windows。 linux。	windows
IsSubscribed	boolean	是否订阅了该镜像的商品码对应的镜像商品的服务条款。	false
ProductCode	string	云市场镜像中的镜像商品标识。	test000****
Architecture	string	镜像系统架构类型。可能值： i386。 x86_64。 arm64。	x86_64
BootMode	string	镜像的启动模式。可能值： BIOS：BIOS 启动模式。 UEFI：UEFI 启动模式。 UEFI-Preferred：双启动模式。更多关于镜像的启动模式说明，请参见镜像启动模式。	BIOS
DiskDeviceMappings	object
DiskDeviceMapping	array<object>	镜像下包含云盘和快照的映射关系集合。
	object	镜像下包含云盘和快照的映射关系。
Type	string	镜像的类型。	system
ImportOSSBucket	string	导入镜像所属 OSS 的 bucket。	testEcsImport
Progress	string	对于复制中的镜像，返回复制任务的进度。	32%
SnapshotId	string	快照 ID。	s-bp17ot2q7x72ggtw****
ImportOSSObject	string	导入镜像所属 OSS 的 object。	imageImport
Device	string	云盘的设备信息，例如/dev/xvdb。	/dev/xvda
Size	string	云盘的大小。单位为 GiB。	60
RemainTime	integer	对于复制中的镜像，返回复制任务的剩余时间，单位：秒。	233
Format	string	镜像格式。	qcow2
Encrypted	boolean	说明该参数正在邀测中。	true
Tags	object
Tag	array<object>	镜像的标签对信息列表。
	object	镜像的标签对信息。
TagValue	string	镜像的标签值。	Oracle
TagKey	string	镜像的标签键。	DTS
IsPublic	boolean	是否为公开镜像。公开镜像包括阿里云提供的公共镜像以及您已发布为社区镜像的自定义镜像。可能值： true：公开镜像。 false：非公开镜像。	false
ImageOwnerId	integer	镜像所属的阿里云账号 ID。该参数仅在查询共享镜像以及社区镜像时生效。	1234567890
LoginAsNonRootSupported	boolean	当前镜像是否支持非 root 用户登录。可能值： true：支持。 false：不支持。	false
SupplierName	string	社区镜像认证企业名称。	TestName
DetectionOptions	object	镜像检测相关结果。
Status	string	镜像检测任务状态。可能值： Processing：检测中。 Finished：检测完成。	Processing
Items	object
Item	array<object>	镜像检测项列表。
	object	镜像检测项。
Name	string	镜像检测项名称。	Nvme
Value	string	镜像检测项结果。	Supported
RiskLevel	string	导入的自定义镜像检测项是否存在风险，如果存在风险返回此字段，不存在风险则不返回。风险等级可能值： High：严重，影响实例能否启动成功，强烈建议修复。 Medium：重要，影响实例启动性能或者实例配置等，建议优化。	High
RiskCode	string	检测项可能存在的缺陷。	NVMe.NotInstalled
Features	object	镜像特性相关属性。
NvmeSupport	string	镜像是否支持 NVMe。可能值： supported：支持。表示以该镜像创建的实例支持 NVMe 协议。 unsupported：不支持。表示以该镜像创建的实例不支持 NVMe 协议。	supported
ImdsSupport	string	镜像的元数据访问模式，可能值： v1：通过该镜像创建 ECS 实例时，不支持将元数据访问模式设置为“仅加固模式”。 v2：通过该镜像创建 ECS 实例时，支持将元数据访问模式设置为“仅加固模式”。实例元数据概述。	v2
CpuOnlineUpgrade	string	是否支持 CPU 热升配。可能值： supported：支持。 unsupported ：不支持。	supported
CpuOnlineDowngrade	string	是否支持 CPU 热降配。可能值： supported：支持。 unsupported ：不支持。	supported
MemoryOnlineUpgrade	string	是否支持内存热升配。可能值： supported：支持。 unsupported ：不支持。	unsupported
MemoryOnlineDowngrade	string	是否支持内存热降配。可能值： supported：支持。 unsupported ：不支持。	unsupported
LicenseType	string	许可证类型。该属性决定了基于此镜像创建 ECS 实例的计费方式和激活逻辑，仅对 Windows Server 类型镜像具有业务参考意义。可能值： Aliyun：阿里云官方许可。基于此镜像创建的实例，将包含 Windows Server 许可费用，实例启动后由阿里云自动激活。 BYOL：自带许可（Bring Your Own License）。基于此镜像创建的实例，不包含 Windows Server 许可费用。实例启动后不会被自动激活，需使用自有合法许可手动激活。	BYOL

示例

正常返回示例

JSON格式

{
  "PageSize": 1,
  "PageNumber": 1,
  "RequestId": "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
  "TotalCount": 1,
  "RegionId": "cn-hangzhou",
  "Images": {
    "Image": [
      {
        "CreationTime": "2019-11-15T06:07:05Z",
        "Status": "Available",
        "ImageFamily": "hangzhou-daily-update",
        "Progress": "100%",
        "IsCopied": false,
        "IsSupportIoOptimized": true,
        "ImageOwnerAlias": "self",
        "IsSupportCloudinit": true,
        "ImageVersion": "2",
        "Usage": "none",
        "IsSelfShared": "true",
        "Description": "Archive log for Oracle",
        "Size": 60,
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "Platform": "Windows Server 2016",
        "OSNameEn": "Windows Server  2016 Data Center Edition 64bit Chinese Edition",
        "ImageName": "testImageName",
        "OSName": "Windows Server  2016 数据中心版 64位中文版",
        "ImageId": "m-bp1g7004ksh0oeuc****",
        "OSType": "windows",
        "IsSubscribed": false,
        "ProductCode": "test000****",
        "Architecture": "x86_64",
        "BootMode": "BIOS",
        "DiskDeviceMappings": {
          "DiskDeviceMapping": [
            {
              "Type": "system",
              "ImportOSSBucket": "testEcsImport",
              "Progress": "32%",
              "SnapshotId": "s-bp17ot2q7x72ggtw****",
              "ImportOSSObject": "imageImport",
              "Device": "/dev/xvda",
              "Size": "60",
              "RemainTime": 233,
              "Format": "qcow2",
              "Encrypted": true
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "Oracle",
              "TagKey": "DTS"
            }
          ]
        },
        "IsPublic": false,
        "ImageOwnerId": 1234567890,
        "LoginAsNonRootSupported": false,
        "SupplierName": "TestName",
        "DetectionOptions": {
          "Status": "Processing",
          "Items": {
            "Item": [
              {
                "Name": "Nvme",
                "Value": "Supported",
                "RiskLevel": "High",
                "RiskCode": "NVMe.NotInstalled"
              }
            ]
          }
        },
        "Features": {
          "NvmeSupport": "supported",
          "ImdsSupport": "v2",
          "CpuOnlineUpgrade": "supported",
          "CpuOnlineDowngrade": "supported",
          "MemoryOnlineUpgrade": "unsupported",
          "MemoryOnlineDowngrade": "unsupported"
        },
        "LicenseType": "BYOL"
      }
    ]
  }
}

错误码

HTTP status code	错误码	错误信息	描述
400	InvalidImageOwnerAlias.ValueNotSupported	The specified ImageOwnerAlias value is not supported.	无效的镜像所有者别名，请您检查该参数是否正确。
400	InvalidParamter	Invalid Parameter.	输入的参数无效。
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	指定的 Tag.N.Key 和 Tag.N.Value 不匹配。
400	InvalidTagCount	The specified tags are beyond the permitted range.	指定的标记超出取值范围。
400	InvalidInstanceType.ValueNotSupported	The specified instance type %s does not exist. You can use the DescribeInstanceTypes API to query the available instance types.	指定的规格不存在，您可以使用DescribeInstanceTypes接口查询可用的规格。
400	InvalidFilterValue.NetworkType	The specified networkType value in the Filter is invalid.	过滤器中指定的网络类型值无效。
400	InvalidOperation.ImageOwnerIdUnsupported	The parameter "ImageOwnerId" is not supported in this context, it is only valid when querying shared images or community images.	此处不支持ImageOwnerId参数，该参数仅在查询共享镜像或社区镜像时有效。
400	InvalidImageOwnerAlias.PublicImageUnsupported	When querying images, the parameter ImageOwnerAlias should be others while specified parameter IsPublic is true.	查询镜像时，参数IsPublic是true，则参数ImageOwnerAlias必须是others。
500	InternalError	The request processing has failed due to some unknown error.
403	CurrentAccount.NotSupportPublicImage	Public image is not supported for current account.	当前用户不支持使用公共镜像。
404	InvalidFilterKey.NotFound	The specified Filter Key is not found.	Filter的Key参数无效。
404	InvalidFilterValue	The specified Filter Value is not valid.	Filter中的Value无效。
404	InvalidUsage	The specified Usage is not valid.	Usage参数无效。
404	InvalidOSType	The specified OSType is not valid.	OSType参数无效。
404	InvalidArchitecture	The specified Architecture is not valid.	Architecture参数无效。

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

变更历史

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