You can call this operation to query available images.

Description

  • 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 images on the returned page. Ten entries are displayed on each page by default.

When you call an API operation through Alibaba Cloud Command Line Interface (CLI), specify request parameter values of different data types in required formats. For more information, see CLI parameter format.

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 No DescribeImages

The operation that you want to perform. Set the value to DescribeImages.
RegionId String Yes cn-hangzhou

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

Status String No Available

The status of the image. Default value: Available. Valid values:

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

Separate multiple parameter values with commas (,).
ImageId String No m-bp1g7004ksh0oeuc3***

The ID of the image.
ShowExpired Boolean No false

Specifies whether subscription images have 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-bp17ot2q7x72ggtwr***

The ID of the snapshot used to create the custom image.
ImageName String No Test

The name of the image.
ImageOwnerAlias String No 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.
  • marketplace: Alibaba Cloud Marketplace images. If Alibaba Cloud Marketplace images are returned in the response, you can directly use the images without subscription. You must pay attention to the billing details of Alibaba Cloud Marketplace images.

This parameter is empty by default, indicating that the results matching system, self, and others are returned.

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 image architecture. Valid values:

  • i386
  • x86_64
PageNumber Integer No 1

The number of the page to return. Pages start from page 1.

Default value: 1.
PageSize Integer No 1

The number of entries to return on each page. Maximum value: 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.
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 the Tag.N.Value parameter to ensure future compatibility.
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 the Tag.N.Key parameter to ensure future compatibility.
Tag.N.Key String No Test

The key of tag N of the image. Valid values of N: 1 to 20.
Tag.N.Value String No Test

The value of tag N of the image. Valid values of N: 1 to 20.
DryRun Boolean No false

Specifies whether to check the validity of the request without actually making the request.

  • true: The validity of the request is checked but resources are not queried. Check items include whether your AccessKey pair is valid, whether RAM users are authorized, and whether the required parameters are specified. If you do not have the required permissions to make this request, the corresponding error message is returned. If the check succeeds, the DryRunOperation error code is returned.
  • false: The request is made, and a 2XX HTTP status code is returned and resources are queried after the request is determined as valid.

Default value: false.
ActionType String No CreateEcs

The scenario in which the images to be queried will be used. Default value: CreateEcs. Valid values:

  • CreateEcs: instance creation
  • ChangeOS: replacement of the system disk or operating system
Filter.N.Key String No CreationStartTime

The key of the filtering condition N.
Filter.N.Value String No 2017-12-05T22:40:00Z

The value of the filtering condition N.
ResourceGroupId String No rg-bp67acfmxazb4ph***

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

Response parameters

Parameter Type Example Description
Images Array

An array consisting of Image data.
Image
Architecture String x86_64

The image architecture. Valid values:

  • i386
  • x86_64
CreationTime String 2018-01-10T01:01:10Z

The time when the image was created.
Description String Archive log for Oracle

The description of the image.
DiskDeviceMappings Array

The mappings between disks and snapshots under the image.
DiskDeviceMapping
Device String /dev/xvdb

The device information of the disk, such as /dev/xvdb.

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

The format of the image.
ImportOSSBucket String testEcsImport

The OSS bucket where an imported image is stored.
ImportOSSObject String imageImport

The OSS object corresponding to an imported image file.
Progress String 32%

The progress of an image copy task.
RemainTime Integer 213

The remaining time for an image copy task. Unit: seconds.
Size String 80

The size of the disk.
SnapshotId String s-bp17ot2q7x72ggtwr***

The ID of the snapshot.
Type String custom

The type of the image.
ImageFamily String as-hangzhou-game-01
ImageId String m-bp1g7004ksh0oeuc3***

The ID of the image.
ImageName String Test

The name of the image.
ImageOwnerAlias String self

The alias of the image owner. Valid values:

  • system: public images provided by Alibaba Cloud.
  • self: your custom images.
  • others: shared images from other Alibaba Cloud accounts.
  • marketplace: Alibaba Cloud Marketplace images.
ImageVersion String 2

The version of the image.
IsCopied Boolean false

Indicates whether the image is a copy of another image.
IsSelfShared String true

Indicates whether the custom image is shared to other Alibaba Cloud accounts.
IsSubscribed Boolean false

Indicates whether you have subscribed to the image corresponding to the specified product code.

IsSupportCloudinit Boolean true

Indicates whether the image supports cloud-init.
IsSupportIoOptimized Boolean true

Indicates whether the image can be used on I/O optimized instances.
OSName String Aliyun Linux 2.1903

The Chinese name of the operating system.
OSNameEn String Aliyun Linux 2.1903

The English name of the operating system.
OSType String Linux

The type of the operating system. Valid values:

  • windows
  • linux
Platform String Aliyun Linux

The platform of the operating system.
ProductCode String jxsc000204

The product code of the Alibaba Cloud Marketplace image.
Progress String 100

The image creation progress. Unit: percent (%).
ResourceGroupId String rg-bp67acfmxazb4ph***

The ID of the resource group to which the image belongs.
Size Integer 80

The size of the image. Unit: GiB.
Status String Available

The status of the image. Valid values:

  • UnAvailable: The image is unavailable.
  • Available: The image is available.
  • Creating: The image is being created.
  • CreateFailed: The image failed to be created.
Tags Array

An array consisting of Tag data.
Tag
TagKey String Test

The tag key of the image.
TagValue String Test

The tag value of the image.
Usage String none

The referenced resource types. Valid values:

  • instance: One or more ECS instances are created.
  • none: No ECS instance is created.
PageNumber Integer 1

The page number of the returned page.
PageSize Integer 1

The number of entries returned per page.
RegionId String cn-hangzhou

The region ID of the image.
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.
TotalCount Integer 24

The total number of images.

Examples

Sample requests

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

Sample success responses

XML format 

<DescribeImagesResponse>
      <PageNumber>1</PageNumber>
      <TotalCount>61</TotalCount>
      <PageSize>1</PageSize>
      <RegionId>cn-hangzhou</RegionId>
      <RequestId>66189103-EDB2-43E2-BB60-BFF2B62F4EB8</RequestId>
      <Images>
            <Image>
                  <ImageId>m-bp1g7004ksh0oeuc3***</ImageId>
                  <Description>Archive log for Oracle</Description>
                  <OSNameEn>Windows Server  2016 Data Center Edition 64bit Chinese Edition</OSNameEn>
                  <ProductCode></ProductCode>
                  <ResourceGroupId></ResourceGroupId>
                  <OSType>windows</OSType>
                  <Architecture>x86_64</Architecture>
                  <OSName>Windows Server  2016 Datacenter edition 64-bit (Chinese)</OSName>
                  <DiskDeviceMappings>
                        <DiskDeviceMapping>
                              <ImportOSSObject></ImportOSSObject>
                              <Format></Format>
                              <Device>/dev/xvda</Device>
                              <Type>system</Type>
                              <SnapshotId>s-bp17ot2q7x72ggtwr***</SnapshotId>
                              <ImportOSSBucket></ImportOSSBucket>
                              <Progress></Progress>
                              <Size>60</Size>
                        </DiskDeviceMapping>
                  </DiskDeviceMappings>
                  <ImageOwnerAlias>self</ImageOwnerAlias>
                  <Progress>100%</Progress>
                  <IsSupportCloudinit>true</IsSupportCloudinit>
                  <Usage>none</Usage>
                  <CreationTime>2019-11-15T06:07:05Z</CreationTime>
                  <ImageVersion></ImageVersion>
                  <Tags>
                        <Tag>
                              <TagValue>Oracle</TagValue>
                              <TagKey>DTS</TagKey>
                        </Tag>
                  </Tags>
                  <Status>Available</Status>
                  <ImageName>Oracle_DTS</ImageName>
                  <IsSupportIoOptimized>true</IsSupportIoOptimized>
                  <IsSelfShared>False</IsSelfShared>
                  <IsCopied>false</IsCopied>
                  <IsSubscribed>false</IsSubscribed>
                  <Platform>Windows Server 2016</Platform>
                  <Size>60</Size>
            </Image>
      </Images>
</DescribeImagesResponse>

JSON format 

{
    "PageNumber": 1,
    "TotalCount": 61,
    "PageSize": 1,
    "RegionId": "cn-hangzhou",
    "RequestId": "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
    "Images": {
        "Image": [
            {
                "ImageId": "m-bp1g7004ksh0oeuc3***",
                "Description": "Archive log for Oracle",
                "OSNameEn": "Windows Server  2016 Data Center Edition 64bit Chinese Edition",
                "ProductCode": "",
                "ResourceGroupId": "",
                "OSType": "windows",
                "Architecture": "x86_64",
                "OSName":"Windows Server  2016 Datacenter edition 64-bit (Chinese)",
                "DiskDeviceMappings": {
                    "DiskDeviceMapping": [
                        {
                            "ImportOSSObject": "",
                            "Format": "",
                            "Device": "/dev/xvda",
                            "Type": "system",
                            "SnapshotId": "s-bp17ot2q7x72ggtwr***",
                            "ImportOSSBucket": "",
                            "Progress": "",
                            "Size": "60"
                        }
                    ]
                },
                "ImageOwnerAlias": "self",
                "Progress": "100%",
                "IsSupportCloudinit": true,
                "Usage": "none",
                "CreationTime": "2019-11-15T06:07:05Z",
                "ImageVersion": "",
                "Tags": {
                    "Tag": [
                        {
                            "TagValue": "Oracle",
                            "TagKey": "DTS"
                        }
                    ]
                },
                "Status": "Available",
                "ImageName": "Oracle_DTS",
                "IsSupportIoOptimized": true,
                "IsSelfShared": "False",
                "IsCopied": false,
                "IsSubscribed": false,
                "Platform": "Windows Server 2016",
                "Size": 60
            }
        ]
    }
}

Error codes

HTTP status code Error code Error message Description
400 InvalidImageOwnerAlias.ValueNotSupported The specified ImageOwnerAlias value is not supported. The error message returned because the specified ImageOwnerAlias parameter is invalid.
400 InvalidParamter Invalid Parameter The error message returned because the specified parameter value is invalid.
404 InvalidFilterKey.NotFound The error message returned because the specified start time or end time is invalid.
404 InvalidUsage The specifed Usage is not valid The error message returned because the specified referenced resource types (image, disk, image_disk, or none) is invalid.
400 InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. The error message returned because the specified Tag.N.Key and Tag.N.Value parameters do not match.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the maximum number of specified tags has been reached.
400 InvalidInstanceType.ValueNotSupported The specified InstanceType does not exist or beyond the permitted range. The error message returned because the specified instance type does not exist or you are not authorized to operate on instances of this instance type.
404 InvalidOSType The specifed OSType is not valid The error message returned because the specified operating system is not supported.
404 InvalidArchitecture The specifed Architecture is not valid The error message returned because the specified Architecture parameter does not exist.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.

For a list of error codes, visit the API Error Center.