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
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:
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:
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:
|
Architecture | String | No | i386 | The architecture of the image. Valid values:
|
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:
|
DryRun | Boolean | No | false | Specifies whether to perform only a dry run, without performing the actual request. Valid values:
Default value: false. |
ActionType | String | No | CreateEcs | The scenario in which the image is used. Default value: CreateEcs. Valid values:
|
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:
|
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 |
IsPublic | Boolean | No | false | Specifies whether to query published community images. Valid values:
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:
|
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:
|
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:
|
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:
|
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:
|
BootMode | String | BIOS | The boot mode of the image. Valid values:
|
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:
|
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:
|
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:
|
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:
|
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:
|
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.