DescribeImages - API Reference| Alibaba Cloud Documentation Center

DescribeImages

Edit in GitHub

Last Updated: Jan 21, 2020 Edit in GitHub

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 users.
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 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
RegionId	String	Yes.	cn-hangzhou	The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.
Action	String	No	DescribeImages	The operation that you want to perform. Set the value to DescribeImages.
ActionType	String	No	CreateEcs	The scenario in which the images to be queried will be used. Valid values: CreateEcs (default): instance creation ChangeOS: replacement of the system disk or operating system
Architecture	String	No	i386	The image architecture. Valid values: i386 x86_64
DryRun	Boolean	No	false	Specifies whether to check the request only. true: The request is checked but available images 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 the check fails, the corresponding error message is returned. If the check succeeds, the DryRunOperation error code is returned. false: The request is checked, and a 2XX HTTP status code is returned and available images are queried if the check succeeds. Default value: false.
Filter.N.Key	String	No	CreationStartTime	The key of the filtering condition.
Filter.N.Value	String	No	2017-12-05T22:40:00Z	The value of the filtering condition.
ImageId	String	No	m-bp1g7004ksh0oeuc3***	The ID of the image.
ImageName	String	No	FinanceJoshua	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 users. 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. Default value: empty, 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.
IsSupportCloudinit	Boolean	No	true	Specifies whether the image supports cloud-init.
IsSupportIoOptimized	Boolean	No	true	Specifies whether the image can be used on I/O optimized instances.
OSType	String	No	linux	The operating system type of the image. Valid values: windows linux
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.
ResourceGroupId	String	No	rg-bp67acfmxazb4ph***	The ID of the resource group to which the custom images belong.
ShowExpired	Boolean	No	false	Specifies whether the subscription of the image has expired. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
SnapshotId	String	No	s-bp17ot2q7x72ggtwr***	The ID of the snapshot used to create the custom images.
Status	String	No	Available	The status of the image. Valid values: Creating: The image is being created. Waiting: Multiple images are waiting to be processed. Available (default): The image is available. UnAvailable: The image is unavailable. CreateFailed: The image failed to be created. Separate multiple parameter values with commas (,).
Tag.N.Key	String	No	FinanceJoshua	The key of tag N for the image. Valid values of N: 1 to 20.
Tag.N.Value	String	No	FinanceDept	The value of tag N for the image. Valid values of N: 1 to 20.
Tag.N.key	String	No	null	The key of tag N for the image. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure compatibility.
Tag.N.value	String	No	null	The value of tag N for the image. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure compatibility.
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.

Response parameters


Parameter	Type	Example	Description
Images	Array		The collection of information of images.
Image			The information of the 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	FinanceDept	The description of the image.
DiskDeviceMappings	Array		The description of the system, including disks and snapshots under the image.
DiskDeviceMapping			The description of the system, including disks and snapshots under the image.
Device	String	/dev/xvdb	The device information of the created disk, such as /dev/xvdb. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure 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 returned 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 created disk.
SnapshotId	String	s-bp17ot2q7x72ggtwr***	The ID of the snapshot.
Type	String	custom	The type of the image.
ImageId	String	m-bp1g7004ksh0oeuc3***	The ID of the image.
ImageName	String	Joshua-Finance	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 users. 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 the user has 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.
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		Tags of the image.
Tag			The tag of the image.
TagKey	String	FinanceDept	The tag key of the image.
TagValue	String	FinanceJoshua	The tag value of the image.
Usage	String	none	The referenced resource types. Valid values: instance none
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 available 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,
	"RequestId":"66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
	"RegionId":"cn-hangzhou",
	"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",
				"Status":"Available",
				"Tags":{
					"Tag":[
						{
							"TagValue":"Oracle",
							"TagKey":"DTS"
						}
					]
				},
				"ImageVersion":"",
				"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 value of the ImageOwnerAlias parameter is invalid.
400	InvalidParamter	Invalid Parameter	The error message returned because the specified parameter is invalid.
404	InvalidFilterKey.NotFound		The error message returned because the specified start time or end time is invalid.
404	InvalidFilterValue		The error message returned because the format of the specified 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 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 exceeds 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 is not supported.
404	InvalidOSType	The specified OSType is not valid	The error message returned because the specified operating system is not supported.
404	InvalidArchitecture	The specified 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 problem persists, submit a ticket.

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