DescribeImages - API Reference| Alibaba Cloud Documentation Center

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

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	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: Creating: The image is being created. Waiting: The image is waiting to be processed. Available: The image is available. UnAvailable: The image is unavailable. CreateFailed: The image cannot be created. Deprecated: The image is discontinued. 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: system: public images provided by Alibaba Cloud. self: custom images that you create. others: shared images from other Alibaba Cloud accounts, or community images published by other Alibaba Cloud accounts. Take note of the following items: To query community images, you must set IsPublic to true. To query shared images, you must set IsPublic to false or leave the IsPublic parameter empty. marketplace: Alibaba Cloud Marketplace images. If Alibaba Cloud Marketplace images are returned in the response, you can use the images without subscription. You must pay attention to the billing details of Alibaba Cloud Marketplace images. 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: windows linux
Architecture	String	No	i386	The image architecture. Valid values: i386 x86_64 arm64
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: instance: The image is already in use and running on an ECS instance. none: The image is not in use.
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 the request is not made. Check items include whether your AccessKey pair is valid, whether RAM users are granted required permissions, and whether the required parameters are specified. If the check fails, the corresponding error is returned. If the check succeeds, the DryRunOperation error code is returned. false: The validity of the request is checked. If the check succeeds, a 2XX HTTP status code is returned, and the request is made. Default value: false.
ActionType	String	No	CreateEcs	The scenario in which the image is used. Default value: CreateEcs. Valid values: CreateEcs: instance creation ChangeOS: replacement of the system disk or operating system
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: true: queries published community images. When you set this parameter to true, you must set ImageOwnerAlias to others. false: queries other image types than community images. The specific image types to be queried are determined by the ImageOwnerAlias value. 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: If you set this parameter to `CreationStartTime`, you can query the resources that were created after the point in time specified by the `Filter.N.Value` value. If you set this parameter to `CreationEndTime`, you can query the resources that were created before the point in time specified by the `Filter.N.Value` value.
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 `Filter.N.Key` parameter. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.

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: UnAvailable: The image is unavailable. Available: The image is available. Creating: The image is being created. CreateFailed: The image cannot be created.
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: system: public images provided by Alibaba Cloud. self: custom images that you create. others: shared images from other Alibaba Cloud accounts, or community images published by other Alibaba Cloud accounts. marketplace: Alibaba Cloud Marketplace images.
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: instance: The image has been used to create one or more ECS instances. none: The image has not been used to create ECS instances.
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: windows linux
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: i386 x86_64 arm64
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: true: The image is a public image. false: The image is not a public image.
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: true: The image supports logons of non-root users. false: The image does not support logons of non-root users.
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.