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 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 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. 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 ID of the image. |
ShowExpired | Boolean | No | false | Specifies whether the subscription image has expired. Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use other parameters. |
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 specify 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 your custom images, public images provided by Alibaba Cloud, shared images from other Alibaba Cloud accounts, and community images published by other Alibaba Cloud accounts 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 | Indicates whether cloud-init is supported by the image. |
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 number of the page to return. Page 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. Valid values:
Default value: false. |
ActionType | String | No | CreateEcs | The scenario in which to use the image. 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. 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. To ensure future compatibility, we recommend that you use the Tag.N.Key parameter. |
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. To ensure future compatibility, we recommend that you use the Tag.N.Value parameter. |
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 |
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 is valid only when you query shared images or community images. |
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
PageSize | Integer | 1 | The number of entries returned per page. |
PageNumber | Integer | 1 | The 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 display name of the operating system in English. |
ImageName | String | testImageName | The name of the image. |
OSName | String | Windows Server 2016 Datacenter 64-bit (Simplified Chinese) | The display name of the operating system in Chinese. |
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 architecture of the image. Valid values:
|
BootMode | String | BIOS | The boot mode of the image. Valid values:
Note You must be aware of the boot modes supported by the specified image. When you use this parameter to change the boot mode of the image, specify a boot mode supported by the image to ensure that instances that use this image can start as expected. |
DiskDeviceMappings | Array of DiskDeviceMapping | The mappings between disks and snapshots that belong to 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. To ensure compatibility, we recommend that you use other parameters. |
Size | String | 60 | The size of the disk. |
RemainTime | Integer | 233 | The amount of remaining 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 is valid 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 certified 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 | Indicates the severity 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 image. | |
NvmeSupport | String | supported | Indicates whether the image supports Non-Volatile Memory Express (NVMe). 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 Edition 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. | 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 parameter does not correspond to the specified Tag.N.Value parameter. |
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 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.