Queries available images.

Usage notes

  • You can query your custom images, public images provided by Alibaba Cloud, Alibaba Cloud Marketplace images, and shared images from other Alibaba Cloud accounts.
  • This operation supports paged query. The response contains the total number of available images and the number of images on the returned page. By default, 10 entries are displayed on each page.
  • When you call an API operation by using Alibaba Cloud CLI, you must specify request parameter values of different data types in the required formats. For more information, see Parameter format overview.
  • If you set ImageOwnerAlias to system or others in the DescribeImages operation to query images that are provided by Alibaba Cloud or shared images, Resource Access Management (RAM) authentication rules are ignored in the operation. For more information, see Authentication rules.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeImages

The operation that you want to perform. Set the value to DescribeImages.

RegionId String Yes cn-hangzhou

The region ID of the image. You can call the DescribeRegions operation to query the most recent region list.

Status String No Available

The state of the image. By default, if you do not specify this parameter, only images in the Available state are returned. Valid values:

  • Creating: The image is being created.
  • Waiting: The image is waiting to be processed.
  • Available: The image is available.
  • UnAvailable: The image is unavailable.
  • CreateFailed: The image failed to be created.
  • Deprecated: The image is deprecated.

Default value: Available. You can specify multiple values for this parameter. Separate the values with commas (,).

ImageId String No m-bp1g7004ksh0oeuc****

The image ID.

ShowExpired Boolean No false

Specifies whether the subscription image has expired.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
SnapshotId String No s-bp17ot2q7x72ggtw****

The ID of the snapshot used to create the custom image.

ImageName String No testImageName

The image name.

ImageFamily String No hangzhou-daily-update

The name of the image family. You can set this parameter to query images of the specified image family.

This parameter is empty by default.

ImageOwnerAlias String No self

The source of the image. Valid values:

  • system: images that are provided by Alibaba Cloud and are not released in Alibaba Cloud Marketplace, which are different from public images in the Elastic Compute Service (ECS) console.
  • self: your custom images
  • others: shared images (images shared by other Alibaba Cloud accounts) and community images (publicly available custom images that are published by other Alibaba Cloud accounts). Take note of the following items:
    • To query community images, you must set IsPublic to true.
    • To query shared images, you must set IsPublic to false or leave IsPublic empty.
  • marketplace: images released by Alibaba Cloud or independent software vendors (ISVs) in the Alibaba Cloud Marketplace, which must be purchased together with ECS instances. Take note of the billing details of the images.

This parameter is empty by default.

Note If you leave this parameter empty, custom images, images provided by Alibaba Cloud, shared images, and community images are queried.
InstanceType String No ecs.g5.large

The instance type for which the image can be used.

IsSupportIoOptimized Boolean No true

Specifies whether the image can be used on I/O optimized instances.

IsSupportCloudinit Boolean No true

Specifies whether the image supports cloud-init.

OSType String No linux

The operating system type of the image. Valid values:

  • windows
  • linux
Architecture String No i386

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
PageNumber Integer No 1

The page number.

Pages start from page 1.

Default value: 1

PageSize Integer No 1

The number of entries per page.

Valid values: 1 to 100.

Default value: 10.

Usage String No instance

Specifies whether the image is running on an ECS instance. Valid values:

  • instance: The image is already in use and running on an ECS instance.
  • none: The image is not in use.
DryRun Boolean No false

Specifies whether to perform only a dry run, without performing the actual request. Valid values:

  • true: performs only a dry run. The system checks whether your AccessKey pair is valid, whether RAM users are granted required permissions, and whether the required parameters are specified. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false: performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.

Default value: false.

ActionType String No CreateEcs

The scenario in which the image is used. Default value: CreateEcs. Valid values:

  • CreateEcs: instance creation
  • ChangeOS: replacement of the system disk or operating system
ResourceGroupId String No rg-bp67acfmxazb4p****

The ID of the resource group to which the custom image belongs. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group are returned.

Note Resources in the default resource group are displayed in the response regardless of how this parameter is set.
Tag.N.key String No null

The key of tag N of the image.

Note This parameter will be removed in the future. We recommend that you use Tag.N.Key to ensure future compatibility.
Tag.N.Key String No TestKey

The key of tag N of the image. Valid values of N: 1 to 20.

If a single tag is specified to query resources, up to 1,000 resources that have this tag added are returned. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added are returned. To query more than 1,000 resources that have the specified tags added, call the ListTagResources operation.

Tag.N.Value String No TestValue

The value of tag N of the image. Valid values of N: 1 to 20.

Tag.N.value String No null

The value of tag N of the image.

Note This parameter will be removed in the future. We recommend that you use Tag.N.Value to ensure future compatibility.
Filter.N.Key String No CreationStartTime

The key of filter N used to query resources. Valid values:

  • If you set this parameter to CreationStartTime, you can query the resources that were created after the point in time specified by the Filter.N.Value value.
  • If you set this parameter to CreationEndTime, you can query the resources that were created before the point in time specified by the Filter.N.Value value.
Filter.N.Value String No 2017-12-05T22:40Z

The value of filter N used to query resources. When you specify this parameter, you must also specify Filter.N.Key. Specify the time in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

IsPublic Boolean No false

Specifies whether to query published community images. Valid values:

  • true: queries published community images. When you set this parameter to true, you must set ImageOwnerAlias to others.
  • false: queries other image types than community images. The specific image types to be queried are determined by the ImageOwnerAlias value.

Default value: false.

ImageOwnerId Long No 1234567890

The ID of the Alibaba Cloud account to which the image belongs. This parameter takes effect only when you query shared images or community images.

Response parameters

Parameter Type Example Description
PageSize Integer 1

The number of entries per page.

PageNumber Integer 1

The page number.

RequestId String 66189103-EDB2-43E2-BB60-BFF2B62F4EB8

The request ID.

TotalCount Integer 1

The total number of images.

RegionId String cn-hangzhou

The region ID of the image.

Images Array of Image

Details about the images.

Image
CreationTime String 2019-11-15T06:07:05Z

The time when the image was created.

Status String Available

The state of the image. Valid values:

  • UnAvailable: The image is unavailable.
  • Available: The image is available.
  • Creating: The image is being created.
  • CreateFailed: The image cannot be created.
ImageFamily String hangzhou-daily-update

The name of the image family of the image.

Progress String 100%

The image creation progress. Unit: percent (%).

IsCopied Boolean false

Indicates whether the image is a copy of another image.

IsSupportIoOptimized Boolean true

Indicates whether the image can be used on I/O optimized instances.

ImageOwnerAlias String self

The source of the image. Valid values:

  • system: public images provided by Alibaba Cloud
  • self: your custom images
  • others: shared images from other Alibaba Cloud accounts, or community images published by other Alibaba Cloud accounts
  • marketplace: Alibaba Cloud Marketplace images
IsSupportCloudinit Boolean true

Indicates whether the image supports cloud-init.

ImageVersion String 2

The image version.

Usage String none

Indicates whether the image was used to create ECS instances. Valid values:

  • instance: The image was used to create one or more ECS instances.
  • none: The image was not used to create ECS instances.
IsSelfShared String true

Indicates whether the custom image was shared to other Alibaba Cloud accounts.

Description String Archive log for Oracle

The image description.

Size Integer 60

The size of the image. Unit: GiB.

ResourceGroupId String rg-bp67acfmxazb4p****

The ID of the resource group to which the image belongs.

Platform String Windows Server 2016

The operating system.

OSNameEn String Windows Server 2016 Data Center Edition 64bit Chinese Edition

The display name of the operating system in English.

ImageName String testImageName

The image name.

OSName String Windows Server 2016 Datacenter 64-bit (Simplified Chinese)

The display name of the operating system in Chinese.

ImageId String m-bp1g7004ksh0oeuc****

The image ID.

OSType String windows

The type of the operating system. Valid values:

  • windows
  • linux
IsSubscribed Boolean false

Indicates whether the Terms of Service of the image service that corresponds to the product code are accepted.

ProductCode String test000****

The Alibaba Cloud Marketplace product code of the image.

Architecture String x86_64

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
BootMode String BIOS

The boot mode of the image. Valid values:

  • BIOS
  • UEFI
DiskDeviceMappings Array of DiskDeviceMapping

The mappings between disks and snapshots in the image.

DiskDeviceMapping
Type String system

The type of the image.

ImportOSSBucket String testEcsImport

The Object Storage Service (OSS) bucket that contains the imported image file.

Progress String 32%

The progress of an image copy task.

SnapshotId String s-bp17ot2q7x72ggtw****

The snapshot ID.

ImportOSSObject String imageImport

The OSS object that corresponds to the imported image file.

Device String /dev/xvda

The device name of the disk. Example: /dev/xvdb.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
Size String 60

The size of the disk. Unit: GiB.

RemainTime Integer 233

The remaining amount of time required for an image copy task. Unit: seconds.

Format String qcow2

The format of the image.

Tags Array of Tag

The tags of the image.

Tag
TagValue String Oracle

The tag value of the image.

TagKey String DTS

The tag key of the image.

IsPublic Boolean false

Indicates whether the image is publicly available. Publicly available images include public images provided by Alibaba Cloud and custom images published as community images. Valid values:

  • true: The image is publicly available.
  • false: The image is not publicly available.
ImageOwnerId Long 1234567890

The ID of the Alibaba Cloud account to which the image belongs. This parameter takes effect only when you query shared images or community images.

LoginAsNonRootSupported Boolean false

Indicates whether the image supports logons of non-root users. Valid values:

  • true: The image supports logons of non-root users.
  • false: The image does not support logons of non-root users.
SupplierName String TestName

The name of the provider that published the community image.

DetectionOptions Object

Details about the check performed on the image.

Status String Processing

The state of the image check task. Valid values:

  • Processing: The image check task is in progress.
  • Finished: The image check task is completed.
Items Array of Item

The check items.

Item
Name String Nvme

The name of the check item.

Value String Supported

The result of the check item.

RiskLevel String High

The severity level of the risk that is detected on the check item of the imported custom image. If the system detects a risk on the check item, this parameter is returned. If the system does not detect a risk on the check item, this parameter is not returned.

Valid values:

  • High: The check item is a high-risk item that may affect the startup of the instance. We recommend that you fix this item at your earliest convenience.
  • Medium: The check item is a medium-risk item that may affect the startup performance or configurations of the instance. We recommend that you fix this item.
RiskCode String NVMe.NotInstallded

The risk that is detected on the check item.

Features Object

The attributes of the custom image.

NvmeSupport String supported

Indicates whether the image supports the Non-Volatile Memory Express (NVMe) protocol. Valid values:

  • supported: The image supports the NVMe protocol. Instances created from this image support NVMe.
  • unsupported: The image does not support the NVMe protocol. Instances that are created from this image do not support the NVMe protocol.

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=DescribeImages
&RegionId=cn-hangzhou
&PageNumber=1
&PageSize=1
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeImagesResponse>
    <TotalCount>1</TotalCount>
    <PageSize>1</PageSize>
    <RequestId>66189103-EDB2-43E2-BB60-BFF2B62F4EB8</RequestId>
    <PageNumber>1</PageNumber>
    <Images>
        <Image>
            <ImageOwnerAlias>self</ImageOwnerAlias>
            <IsSelfShared>true</IsSelfShared>
            <Description>Archive log for Oracle</Description>
            <Platform>Windows Server 2016</Platform>
            <ResourceGroupId>rg-bp67acfmxazb4p****</ResourceGroupId>
            <Size>60</Size>
            <IsSubscribed>false</IsSubscribed>
            <BootMode>BIOS</BootMode>
            <OSName>Windows Server 2016 Datacenter 64-bit (Simplified Chinese)</OSName>
            <IsPublic>false</IsPublic>
            <ImageId>m-bp1g7004ksh0oeuc****</ImageId>
            <DetectionOptions/>
            <Features>
                <NvmeSupport>supported</NvmeSupport>
            </Features>
            <OSNameEn>Windows Server 2016 Data Center Edition 64bit Chinese Edition</OSNameEn>
            <Tags>
                <Tag>
                    <TagKey>DTS</TagKey>
                    <TagValue>Oracle</TagValue>
                </Tag>
            </Tags>
            <LoginAsNonRootSupported>false</LoginAsNonRootSupported>
            <Status>Available</Status>
            <Progress>100%</Progress>
            <Usage>none</Usage>
            <Architecture>x86_64</Architecture>
            <ProductCode>test000****</ProductCode>
            <IsCopied>false</IsCopied>
            <ImageFamily>hangzhou-daily-update</ImageFamily>
            <IsSupportIoOptimized>true</IsSupportIoOptimized>
            <IsSupportCloudinit>true</IsSupportCloudinit>
            <ImageName>testImageName</ImageName>
            <DiskDeviceMappings>
                <DiskDeviceMapping>
                    <SnapshotId>s-bp17ot2q7x72ggtw****</SnapshotId>
                    <Type>system</Type>
                    <Progress>32%</Progress>
                    <Format>qcow2</Format>
                    <Device>/dev/xvda</Device>
                    <Size>60</Size>
                    <ImportOSSBucket>testEcsImport</ImportOSSBucket>
                    <ImportOSSObject>imageImport</ImportOSSObject>
                </DiskDeviceMapping>
            </DiskDeviceMappings>
            <ImageVersion>2</ImageVersion>
            <OSType>windows</OSType>
            <CreationTime>2019-11-15T06:07:05Z</CreationTime>
        </Image>
    </Images>
    <RegionId>cn-hangzhou</RegionId>
</DescribeImagesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalCount" : 1,
  "PageSize" : 1,
  "RequestId" : "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
  "PageNumber" : 1,
  "Images" : {
    "Image" : [ {
      "ImageOwnerAlias" : "self",
      "IsSelfShared" : "true",
      "Description" : "Archive log for Oracle",
      "Platform" : "Windows Server 2016",
      "ResourceGroupId" : "rg-bp67acfmxazb4p****",
      "Size" : 60,
      "IsSubscribed" : false,
      "BootMode" : "BIOS",
      "OSName": "Windows Server 2016 Datacenter 64-bit (Simplified Chinese)",
      "IsPublic" : false,
      "ImageId" : "m-bp1g7004ksh0oeuc****",
      "DetectionOptions" : { },
      "Features" : {
        "NvmeSupport" : "supported"
      },
      "OSNameEn" : "Windows Server 2016 Data Center Edition 64bit Chinese Edition",
      "Tags" : {
        "Tag" : [ {
          "TagKey" : "DTS",
          "TagValue" : "Oracle"
        } ]
      },
      "LoginAsNonRootSupported" : false,
      "Status" : "Available",
      "Progress" : "100%",
      "Usage" : "none",
      "Architecture" : "x86_64",
      "ProductCode" : "test000****",
      "IsCopied" : false,
      "ImageFamily" : "hangzhou-daily-update",
      "IsSupportIoOptimized" : true,
      "IsSupportCloudinit" : true,
      "ImageName" : "testImageName",
      "DiskDeviceMappings" : {
        "DiskDeviceMapping" : [ {
          "SnapshotId" : "s-bp17ot2q7x72ggtw****",
          "Type" : "system",
          "Progress" : "32%",
          "Format" : "qcow2",
          "Device" : "/dev/xvda",
          "Size" : "60",
          "ImportOSSBucket" : "testEcsImport",
          "ImportOSSObject" : "imageImport"
        } ]
      },
      "ImageVersion" : "2",
      "OSType" : "windows",
      "CreationTime" : "2019-11-15T06:07:05Z"
    } ]
  },
  "RegionId" : "cn-hangzhou"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidImageOwnerAlias.ValueNotSupported The specified ImageOwnerAlias value is not supported. Invalid ImageOwnerAlias value.
400 InvalidParamter Invalid Parameter. Invalid parameter.
400 InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. Tag.N.Key and Tag.N.Value do not correspond to each other.
400 InvalidTagCount The specified tags are beyond the permitted range. The maximum number of specified tags is exceeded.
400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The InstanceType is not found or you are not authorized to manage instances of this instance type.
403 CurrentAccount.NotSupportPublicImage Public image is not supported for current account. The current account cannot use public images.
404 InvalidFilterKey.NotFound The specified Filter Key is not found. Invalid Filter.N.Key value.
404 InvalidFilterValue The specified Filter Value is not valid. Invalid Filter.N.Value value.
404 InvalidUsage The specified Usage is not valid. Invalid Usage value.
404 InvalidOSType The specified OSType is not valid. Invalid OSType value.
404 InvalidArchitecture The specified Architecture is not valid. Invalid Architecture value.
500 InternalError The request processing has failed due to some unknown error. An internal error occurred. Try again later.

For a list of error codes, see Service error codes.