全部产品
Search
文档中心

云服务器 ECS:DescribeImages - 查询可以使用的镜像资源

更新时间:Dec 24, 2024

调用DescribeImages接口,并可以指定ImageId、ImageFamily、InstanceType等参数,查询您可以使用的镜像资源。

接口说明

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

调试

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

授权信息

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

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
ecs:DescribeImagesget
*Image
acs:ecs:{#regionId}:{#accountId}:image/*
*Image
acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

请求参数

名称类型必填描述示例值
RegionIdstring

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

cn-hangzhou
Statusstring

查询指定状态的镜像,如果不配置此参数,默认只返回 Available 状态的镜像。取值范围:

  • Creating:镜像正在创建中。
  • Waiting:多任务排队中。
  • Available(默认):您可以使用的镜像。
  • UnAvailable:您不能使用的镜像。
  • CreateFailed:创建失败的镜像。
  • Deprecated:已弃用的镜像。

默认值:Available。当前参数支持同时取多个值,值之间以半角逗号(,)隔开。

Available
ImageIdstring

镜像 ID。

m-bp1g7004ksh0oeuc****
ShowExpiredboolean

订阅型镜像是否已经超过使用期限。

false
SnapshotIdstring

根据某一快照 ID 创建的自定义镜像。

s-bp17ot2q7x72ggtw****
ImageNamestring

镜像名称。

testImageName
ImageFamilystring

镜像族系名称,查询镜像时可通过设置该参数来过滤当前族系对应的镜像。

默认值:空。

说明 阿里云官方镜像关联的镜像族系信息请参见公共镜像概述
hangzhou-daily-update
ImageOwnerAliasstring

镜像来源。取值范围:

  • system:阿里云官方提供的,且不是通过云市场发布的镜像,和控制台中的“公共镜像”概念不同。
  • self:您创建的自定义镜像。
  • others:包含共享镜像(其他阿里云用户直接共享给您的镜像)和社区镜像(任意阿里云用户将其自定义镜像完全公开共享后的镜像)。您需要注意:
    • 查找社区镜像时,IsPublic 必须为 true。
    • 查找共享镜像时,IsPublic 需要设置为 false 或者不传值。
  • marketplace:阿里云或者第三方供应商 ISV 在云市场发布的镜像,需要和 ECS 一起购买。请自行留意云市场镜像的收费详情。

默认值:空。

说明 空表示返回取值为 system、self 以及 others 的结果。
self
InstanceTypestring

为指定的实例规格查询可以使用的镜像。

ecs.g5.large
IsSupportIoOptimizedboolean

镜像是否可以运行在 I/O 优化实例上。

true
IsSupportCloudinitboolean

镜像是否支持 cloud-init。

true
OSTypestring

镜像的操作系统类型。取值范围:

  • windows。
  • linux。
linux
Architecturestring

镜像的体系架构。取值范围:

  • i386。
  • x86_64。
  • arm64。
i386
PageNumberinteger

镜像资源列表的页码。

起始值:1。

默认值:1。

1
PageSizeinteger

分页查询时设置的每页行数。

最大值:100。

默认值:10。

10
Usagestring

镜像是否已经运行在 ECS 实例中。取值范围:

  • instance:镜像处于运行状态,有 ECS 实例使用。
  • none:镜像处于闲置状态,暂无 ECS 实例使用。
instance
DryRunboolean

是否只预检此次请求。

  • true:发送检查请求,不会查询资源状况。检查项包括 AccessKey 是否有效、RAM 用户的授权情况和是否填写了必需参数。如果检查不通过,则返回对应错误。如果检查通过,会返回错误码 DryRunOperation。
  • false:发送正常请求,通过检查后返回 2XX HTTP 状态码并直接查询资源状况。

默认值:false。

false
ActionTypestring

镜像需要被使用到的场景。取值范围:

  • CreateEcs(默认):创建实例。
  • ChangeOS:更换系统盘/更换操作系统。
CreateEcs
ResourceGroupIdstring

自定义镜像所在的企业资源组 ID。使用该参数过滤资源时,资源数量不能超过 1000 个。

说明 不支持默认资源组过滤。
rg-bp67acfmxazb4p****
Tagarray<object>

标签列表。

object

标签列表。

keystring

镜像的标签键。

说明 该参数即将被弃用,为提高兼容性,建议您使用另一个Tag.N.Key参数。
null
Keystring

镜像的标签键。N 的取值范围:1~20。

使用一个标签过滤资源,查询到该标签下的资源数量不能超过 1000 个;使用多个标签过滤资源,查询到同时绑定了多个标签的资源数量不能超过 1000 个。如果资源数量超过 1000 个,请使用 ListTagResources 接口进行查询。

TestKey
Valuestring

镜像的标签值。N 的取值范围:1~20。

TestValue
valuestring

镜像的标签值。

说明 该参数即将被弃用,为提高兼容性,建议您使用另一个Tag.N.Value参数。
null
Filterarray<object>

查询资源时的筛选条件列表。

object

查询资源时的筛选条件列表。

Keystring

查询资源时的筛选键。取值范围:

  • 当该参数取值为CreationStartTime时,可以查询在指定时间点(Filter.N.Value)后创建的资源信息。
  • 当该参数取值为CreationEndTime时,可以查询在指定时间点(Filter.N.Value)前创建的资源信息。
  • 当该参数取值为NetworkType时,可以查询指定网络类型的资源信息。
CreationStartTime
Valuestring

查询资源时的筛选值。

  • 当(Filter.N.Key)为CreationStartTimeCreationEndTime时,格式为:yyyy-MM-ddTHH:mmZ,采用 UTC+0 时区。
  • 当(Filter.N.Key)为NetworkType时,可以指定网络类型的值有:vpcclassic等。
2017-12-05T22:40Z
IsPublicboolean

是否查询已发布的社区镜像。取值范围:

  • true:查询已发布的社区镜像。当您指定该参数值为 true 时,ImageOwnerAlias 必须为 others。
  • false:查询除社区镜像的其他镜像类型,具体以 ImageOwnerAlias 参数值为准。

默认值:false。

false
ImageOwnerIdlong

镜像所属的阿里云账号 ID。该参数仅在查询共享镜像以及社区镜像时生效。

20169351435666****

返回参数

名称类型描述示例值
object
PageSizeinteger

当前分页包含多少条目。

1
PageNumberinteger

当前页码。

1
RequestIdstring

请求 ID。

66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCountinteger

镜像总数。

1
RegionIdstring

镜像所属地域 ID。

cn-hangzhou
Imagesarray<object>

镜像信息 Images 组成的集合。

Imageobject

镜像信息 images 组成的集合。

CreationTimestring

镜像的创建时间。

2019-11-15T06:07:05Z
Statusstring

镜像的状态。可能值:

  • UnAvailable:不可用。
  • Available:可用。
  • Creating:创建中。
  • CreateFailed:创建失败。
Available
ImageFamilystring

镜像族系名称。

hangzhou-daily-update
Progressstring

镜像完成的进度,单位为百分比。

100%
IsCopiedboolean

是否是拷贝的镜像。

false
IsSupportIoOptimizedboolean

是否可以在 I/O 优化实例上运行。

true
ImageOwnerAliasstring

镜像来源。可能值:

  • system:阿里云提供的公共镜像。
  • self:您创建的自定义镜像。
  • others:其他阿里云用户提供的共享镜像或社区镜像。
  • marketplace:云市场镜像提供的镜像。
self
IsSupportCloudinitboolean

是否支持 Cloud Init。

true
ImageVersionstring

镜像版本。

2
Usagestring

有引用关系的资源类型。可能值:

  • instance:创建了一台或多台 ECS 实例。
  • none:未创建过 ECS 实例。
none
IsSelfSharedstring

是否共享过该自定义镜像给其他用户。

true
Descriptionstring

描述信息。

Archive log for Oracle
Sizeinteger

镜像大小,单位:GiB。

注意 如果镜像包含数据盘,此参数仅代表镜像关联的系统盘快照大小。

60
ResourceGroupIdstring

镜像所在的企业资源组 ID。

rg-bp67acfmxazb4p****
Platformstring

操作系统平台。

Windows Server 2016
OSNameEnstring

操作系统的英文显示名称。

Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageNamestring

镜像的名称。

testImageName
OSNamestring

操作系统的中文显示名称。

Windows Server 2016 数据中心版 64位中文版
ImageIdstring

镜像 ID。

m-bp1g7004ksh0oeuc****
OSTypestring

操作系统类型。可能值:

  • windows。
  • linux。
windows
IsSubscribedboolean

是否订阅了该镜像的商品码对应的镜像商品的服务条款。

false
ProductCodestring

云市场镜像中的镜像商品标识。

test000****
Architecturestring

镜像系统架构类型。可能值:

  • i386。
  • x86_64。
  • arm64。
x86_64
BootModestring

镜像的启动模式。可能值:

  • BIOS:BIOS 启动模式。

  • UEFI:UEFI 启动模式。

  • UEFI-Preferred:双启动模式。

更多关于镜像的启动模式说明,请参见镜像启动模式

BIOS
DiskDeviceMappingsarray<object>

镜像下包含云盘和快照的映射关系。

DiskDeviceMappingobject

镜像下包含云盘和快照的映射关系。

Typestring

镜像的类型。

system
ImportOSSBucketstring

导入镜像所属 OSS 的 bucket。

testEcsImport
Progressstring

对于复制中的镜像,返回复制任务的进度。

32%
SnapshotIdstring

快照 ID。

s-bp17ot2q7x72ggtw****
ImportOSSObjectstring

导入镜像所属 OSS 的 object。

imageImport
Devicestring

云盘的设备信息,例如/dev/xvdb。

/dev/xvda
Sizestring

云盘的大小。单位为 GiB。

60
RemainTimeinteger

对于复制中的镜像,返回复制任务的剩余时间,单位:秒。

233
Formatstring

镜像格式。

qcow2
Encryptedstring
说明 该参数正在邀测中。
true
Tagsarray<object>

镜像的标签对信息。

Tagobject

镜像的标签对信息。

TagValuestring

镜像的标签值。

Oracle
TagKeystring

镜像的标签键。

DTS
IsPublicboolean

是否为公开镜像。公开镜像包括阿里云提供的公共镜像以及您已发布为社区镜像的自定义镜像。可能值:

  • true:公开镜像。
  • false:非公开镜像。
false
ImageOwnerIdlong

镜像所属的阿里云账号 ID。该参数仅在查询共享镜像以及社区镜像时生效。

1234567890
LoginAsNonRootSupportedboolean

当前镜像是否支持非 root 用户登录。可能值:

  • true:支持。

  • false:不支持。

false
SupplierNamestring

社区镜像认证企业名称。

TestName
DetectionOptionsobject

镜像检测相关结果。

Statusstring

镜像检测任务状态。可能值:

  • Processing:检测中。

  • Finished:检测完成。

Processing
Itemsarray<object>

镜像检测项列表。

Itemobject

镜像检测项列表。

Namestring

镜像检测项名称。

Nvme
Valuestring

镜像检测项结果。

Supported
RiskLevelstring

导入的自定义镜像检测项是否存在风险,如果存在风险返回此字段,不存在风险则不返回。

风险等级可能值:

  • High:严重,影响实例能否启动成功,强烈建议修复。

  • Medium:重要,影响实例启动性能或者实例配置等,建议优化。

High
RiskCodestring

检测项可能存在的缺陷。

NVMe.NotInstalled
Featuresobject

镜像特性相关属性。

NvmeSupportstring

镜像是否支持 NVMe。可能值:

  • supported:支持。表示以该镜像创建的实例支持 NVMe 协议。

  • unsupported:不支持。表示以该镜像创建的实例不支持 NVMe 协议。

supported
ImdsSupportstring

镜像的元数据访问模式,可能值:

  • v1:通过该镜像创建 ECS 实例时,不支持将元数据访问模式设置为“仅加固模式”。
  • v2:通过该镜像创建 ECS 实例时,支持将元数据访问模式设置为“仅加固模式”。
v2

示例

正常返回示例

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": "",
          "CpuOnlineDowngrade": "",
          "MemoryOnlineUpgrade": "",
          "MemoryOnlineDowngrade": ""
        }
      }
    ]
  }
}

错误码

HTTP status code错误码错误信息描述
400InvalidImageOwnerAlias.ValueNotSupportedThe specified ImageOwnerAlias value is not supported.无效的镜像所有者别名,请您检查该参数是否正确。
400InvalidParamterInvalid Parameter.输入的参数无效。
400InvalidTag.MismatchThe specified Tag.n.Key and Tag.n.Value are not match.指定的 Tag.N.Key 和 Tag.N.Value 不匹配。
400InvalidTagCountThe specified tags are beyond the permitted range.指定的标记超出取值范围。
400InvalidInstanceType.ValueNotSupportedThe specified InstanceType does not exist or beyond the permitted range.您指定的实例规格不存在,或者您没有权限操作此规格的实例。
400InvalidFilterValue.NetworkTypeThe specified networkType value in the Filter is invalid.过滤器中指定的网络类型值无效。
403CurrentAccount.NotSupportPublicImagePublic image is not supported for current account.当前用户不支持使用公共镜像。
404InvalidFilterKey.NotFoundThe specified Filter Key is not found.Filter的Key参数无效。
404InvalidFilterValueThe specified Filter Value is not valid.Filter中的Value无效。
404InvalidUsageThe specified Usage is not valid.Usage参数无效。
404InvalidOSTypeThe specified OSType is not valid.OSType参数无效。
404InvalidArchitectureThe specified Architecture is not valid.Architecture参数无效。
500InternalErrorThe request processing has failed due to some unknown error.内部错误,请重试。

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

变更历史

变更时间变更内容概要操作
2024-12-20OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2024-12-17OpenAPI 描述信息更新、OpenAPI 错误码发生变更查看变更详情
2024-12-16OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2024-12-05OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情
2024-09-26OpenAPI 错误码发生变更查看变更详情
2023-03-30OpenAPI 错误码发生变更查看变更详情
2021-07-26OpenAPI 错误码发生变更、OpenAPI 返回结构发生变更查看变更详情