Queries 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. By default, ten 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.
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. Default value: Available. Valid values:
You can specify multiple values. Separate the values with commas (,). |
ImageId | String | No | m-bp1g7004ksh0oeuc**** |
The ID of the image. |
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 name of the image. |
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, which indicates that the results that match 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:
|
Architecture | String | No | i386 |
The image architecture. Valid values:
|
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 Elastic Compute Service (ECS) instance. Valid values:
|
DryRun | Boolean | No | false |
Specifies whether to check the validity of the request without actually making the request.
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 can be displayed in the response. |
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. |
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 | 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 can be displayed in the response. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added can be displayed in the response. To query more than 1,000 resources that have 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 the
Tag.N.Value parameter 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 the |
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
PageSize | Integer | 1 |
The number of entries returned per page. |
PageNumber | Integer | 1 |
The page number of the returned page. |
RequestId | String | 66189103-EDB2-43E2-BB60-BFF2B62F4EB8 |
The ID of the request. |
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. |
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 version of the image. |
Usage | String | none |
Indicates whether the image has been 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 description of the image. |
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 English name of the operating system. |
ImageName | String | testImageName |
The name of the image. |
OSName | String | Windows Server 2016 Datacenter 64-bit (Simplified Chinese) |
The Chinese name of the operating system. |
ImageId | String | m-bp1g7004ksh0oeuc**** |
The ID of the image. |
OSType | String | windows |
The type of the operating system. Valid values:
|
IsSubscribed | Boolean | false |
Indicates whether you have subscribed to the image that corresponds to the specified product code. |
ProductCode | String | test000**** |
The product code of the Alibaba Cloud Marketplace image. |
Architecture | String | x86_64 |
The image architecture. 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 ID of the snapshot. |
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. |
RemainTime | Integer | 233 |
The remaining time 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 a public image. Public 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 supplier that publishes the community image. |
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>
<PageSize>1</PageSize>
<PageNumber>1</PageNumber>
<RequestId>66189103-EDB2-43E2-BB60-BFF2B62F4EB8</RequestId>
<TotalCount>1</TotalCount>
<RegionId>cn-hangzhou</RegionId>
<Images>
<CreationTime>2019-11-15T06:07:05Z</CreationTime>
<Status>Available</Status>
<ImageFamily>hangzhou-daily-update</ImageFamily>
<Progress>100%</Progress>
<IsCopied>false</IsCopied>
<IsSupportIoOptimized>true</IsSupportIoOptimized>
<ImageOwnerAlias>self</ImageOwnerAlias>
<IsSupportCloudinit>true</IsSupportCloudinit>
<ImageVersion>2</ImageVersion>
<Usage>none</Usage>
<IsSelfShared>true</IsSelfShared>
<Description>Archive log for Oracle</Description>
<Size>60</Size>
<ResourceGroupId>rg-bp67acfmxazb4p****</ResourceGroupId>
<Platform>Windows Server 2016</Platform>
<OSNameEn>Windows Server 2016 Data Center Edition 64bit Chinese Edition</OSNameEn>
<ImageName>testImageName</ImageName>
<OSName>Windows Server 2016 Datacenter 64-bit (Simplified Chinese)</OSName>
<ImageId>m-bp1g7004ksh0oeuc****</ImageId>
<OSType>windows</OSType>
<IsSubscribed>false</IsSubscribed>
<ProductCode>test000****</ProductCode>
<Architecture>x86_64</Architecture>
<DiskDeviceMappings>
<Type>system</Type>
<ImportOSSBucket>testEcsImport</ImportOSSBucket>
<Progress>32%</Progress>
<SnapshotId>s-bp17ot2q7x72ggtw****</SnapshotId>
<ImportOSSObject>imageImport</ImportOSSObject>
<Device>/dev/xvda</Device>
<Size>60</Size>
<RemainTime>233</RemainTime>
<Format>qcow2</Format>
</DiskDeviceMappings>
<Tags>
<TagValue>Oracle</TagValue>
<TagKey>DTS</TagKey>
</Tags>
<IsPublic>false</IsPublic>
<ImageOwnerId>1234567890</ImageOwnerId>
<LoginAsNonRootSupported>false</LoginAsNonRootSupported>
<SupplierName>TestName</SupplierName>
</Images>
</DescribeImagesResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"PageSize": 1,
"PageNumber": 1,
"RequestId": "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
"TotalCount": 1,
"RegionId": "cn-hangzhou",
"Images": {
"Images": [
{
"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 Datacenter Edition 64-bit (Chinese)",
"ImageId": "m-bp1g7004ksh0oeuc****",
"OSType": "windows",
"IsSubscribed": false,
"ProductCode": "test000****",
"Architecture": "x86_64",
"DiskDeviceMappings": {
"DiskDeviceMappings": [
{
"Type": "system",
"ImportOSSBucket": "testEcsImport",
"Progress": "32%",
"SnapshotId": "s-bp17ot2q7x72ggtw****",
"ImportOSSObject": "imageImport",
"Device": "/dev/xvda",
"Size": "60",
"RemainTime": 233,
"Format": "qcow2"
}
]
},
"Tags": {
"Tag": [
{
"TagValue": "Oracle",
"TagKey": "DTS"
}
]
},
"IsPublic": false,
"ImageOwnerId": 1234567890,
"LoginAsNonRootSupported": false,
"SupplierName": "TestName"
},
]
},
}
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 a specified parameter 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 correspond to each other. |
400 | InvalidTagCount | The specified tags are beyond the permitted range. | The error message returned because the number of specified tags has exceeded the upper limit. |
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 because you are not authorized to manage instances of the specified instance type. |
404 | InvalidUsage | The specifed Usage is not valid | The error message returned because the specified Usage parameter is invalid. |
404 | InvalidOSType | The specifed OSType is not valid | The error message returned because the specified OSType parameter is invalid. |
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 error persists, submit a ticket. |
For a list of error codes, visit the API Error Center.