Use DescribeImages to query image resources - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Queries the list of available image resources based on specified parameters such as ImageId, image usage scenarios, and filter conditions.

Operation description

Image resources that you can query include your custom images, public images provided by Alibaba Cloud, Alibaba Cloud Marketplace images, and shared images that other Alibaba Cloud users have shared with you.
Paging is supported. The query results include the total number of available image resources and the image resources on the current page. The default number of entries per page is 10.
When you invoke an API operation by using Cloud Assistant CLI, request parameters of different data types must comply with format requirements. For more information, see CLI parameter format.
When you query images provided by Alibaba Cloud or shared images (ImageOwnerAlias is set to system or others), the request can bypass RAM authentication rules. For more information, see Authentication rules.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:DescribeImages

get

Image

acs:ecs:{#regionId}:{#accountId}:image/*

Image

acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the image. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
Status	string	No	The status of the image. If you do not specify this parameter, only images in the Available state are returned by default. Valid values: Creating: The image is being created. Waiting: The image is waiting in a multi-task queue. Available (default): The image is available for use. UnAvailable: The image is unavailable. CreateFailed: The image failed to be created. Deprecated: The image is deprecated. Default value: Available. This parameter supports multiple values at the same time, separated by commas (,).	Available
ImageId	string	No	The image ID. Naming conventions for image IDs Public images: Named by operating system version, architecture, language, and release date. For example, the image ID for Windows Server 2008 R2 Enterprise Edition, 64-bit English system is win2008r2_64_ent_sp1_en-us_40G_alibase_20190318.vhd. Custom images, shared images, Alibaba Cloud Marketplace images, and community images: Start with m.	m-bp1g7004ksh0oeuc****
ShowExpired	boolean	No	Specifies whether the subscription image has expired.	false
SnapshotId	string	No	The ID of the snapshot used to create the custom image.	s-bp17ot2q7x72ggtw****
ImageName	string	No	The image name. Fuzzy search is supported.	testImageName
ImageFamily	string	No	The name of the image family. You can set this parameter to filter images that belong to the specified image family. Default value: empty. Note For information about image families associated with Alibaba Cloud official images, see Overview of public images.	hangzhou-daily-update
ImageOwnerAlias	string	No	The source of the image. Valid values: system: Public images provided by Alibaba Cloud that are not published through Alibaba Cloud Marketplace. This is different from the concept of "public images" in the console. self: Custom images that you created. others: Includes shared images (images directly shared by other Alibaba Cloud users) and community images (custom images that are fully shared by any Alibaba Cloud user). Note the following: To query community images, IsPublic must be set to true. To query shared images, IsPublic must be set to false or left empty. marketplace: Images published by Alibaba Cloud or third-party independent software vendors (ISVs) in Alibaba Cloud Marketplace. These images must be purchased together with ECS. Check the billing details of Alibaba Cloud Marketplace images. Default value: empty. Note An empty value indicates that images with the system, self, and others values are returned.	self
InstanceType	string	No	The instance type for which you want to query available images.	ecs.g5.large
IsSupportIoOptimized	boolean	No	Specifies whether the image can run on I/O optimized instances.	true
IsSupportCloudinit	boolean	No	Specifies whether the image supports cloud-init.	true
OSType	string	No	The operating system type of the image. Valid values: windows. linux.	linux
Architecture	string	No	The architecture of the image. Valid values: i386. x86_64. arm64.	i386
PageNumber	integer	No	The page number of the resources. Start value: 1. Default value: 1.	1
PageSize	integer	No	The number of entries per page for paging. Maximum value: 100. Default value: 10.	10
Usage	string	No	Specifies whether the image is running on ECS instances. Valid values: instance: The image is in use. ECS instances are created from this image. none: The image is idle. No ECS instances are created from this image.	instance
DryRun	boolean	No	Specifies whether to perform only a dry run. true: Sends a dry run request without querying resource status. The system checks whether your AccessKey pair is valid, whether Resource Access Management (RAM) user authorization is granted, 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: Sends a normal request. After the check succeeds, a 2XX HTTP status code is returned and the resource status is queried. Default value: false.	false
ActionType	string	No	The scenario in which the image is used. Valid values: CreateEcs (default): instance creation. ChangeOS: replacement of the system disk or operating system.	CreateEcs
ResourceGroupId	string	No	The ID of the resource group to which the custom image belongs. When you use this parameter to filter resources, the resource count cannot exceed 1,000. Note Filtering by the default resource group is not supported.	rg-bp67acfmxazb4p****
Tag	array<object>	No	The list of tags.
	object	No	The tag information.
key	string	No	The tag key of the image. Note This parameter will be deprecated. To improve compatibility, use Tag.N.Key instead.	null
Key	string	No	The tag key of the image. Valid values of N: 1 to 20. When you use a single tag to filter resources, the resource count with this tag cannot exceed 1,000. When you use multiple tags to filter resources, the resource count of resources that are attached to all specified tags cannot exceed 1,000. If the resource count exceeds 1,000, call the ListTagResources operation.	TestKey
Value	string	No	The tag value of the image. Valid values of N: 1 to 20.	TestValue
value	string	No	The tag value of the image. Note This parameter will be deprecated. To improve compatibility, use Tag.N.Value instead.	null
Filter	array<object>	No	The list of filter conditions for querying resources.
	object	No	The filter condition for querying resources.
Key	string	No	The filter key for querying resources. Valid values: When this parameter is set to `CreationStartTime`, you can query resources created after the specified time point (`Filter.N.Value`). When this parameter is set to `CreationEndTime`, you can query resources created before the specified time point (`Filter.N.Value`). When this parameter is set to `NetworkType`, you can query resources of the specified network type. When this parameter is set to any of `CpuOnlineUpgrade`, `CpuOnlineDowngrade`, `MemoryOnlineUpgrade`, or `MemoryOnlineDowngrade`, you can query the CPU or memory hot-plugging support of the specified image. Default value: null.	CreationStartTime
Value	string	No	The filter value for querying resources. When `Filter.N.Key` is set to `CreationStartTime` or `CreationEndTime`, the format is `yyyy-MM-ddTHH:mmZ`, using the UTC+0 time zone. When `Filter.N.Key` is set to `NetworkType`, valid network type values include `vpc` and `classic`. When `Filter.N.Key` is set to `CpuOnlineUpgrade`, `CpuOnlineDowngrade`, `MemoryOnlineUpgrade`, or `MemoryOnlineDowngrade`, the value can be `supported` or `unsupported`. Default value: null.	2017-12-05T22:40Z
IsPublic	boolean	No	Specifies whether to query published community images. Valid values: true: Queries published community images. When you set this parameter to true, ImageOwnerAlias must be set to others. false: Queries image types other than community images. The specific types depend on the ImageOwnerAlias parameter value. Default value: false.	false
ImageOwnerId	integer	No	The Alibaba Cloud account ID of the image owner. This parameter takes effect only when you query shared images or community images.	20169351435666****

Response elements

Element	Type	Description	Example
	object
PageSize	integer	The number of entries on the current page.	1
PageNumber	integer	The current page number.	1
RequestId	string	The request ID.	66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCount	integer	The total number of images.	1
RegionId	string	The region ID of the image.	cn-hangzhou
Images	object
Image	array<object>	The collection of image information.
	array<object>	The image information.
CreationTime	string	The time when the image was created.	2019-11-15T06:07:05Z
Status	string	The status of the image. Valid values: UnAvailable: unavailable. Available: available. Creating: being created. CreateFailed: creation failed.	Available
ImageFamily	string	The name of the image family.	hangzhou-daily-update
Progress	string	The image creation progress, in percentage.	100%
IsCopied	boolean	Indicates whether the image is a copy of another image.	false
IsSupportIoOptimized	boolean	Indicates whether the image can run on I/O optimized instances.	true
ImageOwnerAlias	string	The source of the image. Valid values: system: A public image provided by Alibaba Cloud. self: A custom image that you created. others: A shared image or community image provided by other Alibaba Cloud users. marketplace: An Alibaba Cloud Marketplace image.	self
IsSupportCloudinit	boolean	Indicates whether the image supports Cloud Init.	true
ImageVersion	string	The image version.	2
Usage	string	The type of resource that references the image. Valid values: instance: One or more ECS instances have been created from the image. none: No ECS instances have been created from the image.	none
IsSelfShared	string	Indicates whether the custom image has been shared with other users.	true
Description	string	The description of the image.	Archive log for Oracle
Size	integer	The image size, in GiB. Important If the image contains data disks, this parameter represents only the size of the system disk snapshot associated with the image.	60
ResourceGroupId	string	The ID of the resource group to which the image belongs.	rg-bp67acfmxazb4p****
Platform	string	The operating system platform.	Windows Server 2016
OSNameEn	string	The English display name of the operating system.	Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageName	string	The name of the image.	testImageName
OSName	string	The Chinese display name of the operating system.	Windows Server 2016 数据中心版 64位中文版
ImageId	string	The image ID.	m-bp1g7004ksh0oeuc****
OSType	string	The operating system type. Valid values: windows. linux.	windows
IsSubscribed	boolean	Indicates whether you have subscribed to the terms of service for the image product corresponding to the product code.	false
ProductCode	string	The product code of the Alibaba Cloud Marketplace image.	test000****
Architecture	string	The system architecture of the image. Valid values: i386. x86_64. arm64.	x86_64
BootMode	string	The boot mode of the image. Valid values: BIOS: BIOS boot mode. UEFI: UEFI boot mode. UEFI-Preferred: dual boot mode. For more information about image boot modes, see Image boot mode.	BIOS
DiskDeviceMappings	object
DiskDeviceMapping	array<object>	The collection of disk-to-snapshot mapping relationships in the image.
	object	The disk-to-snapshot mapping relationship in the image.
Type	string	The type of the image.	system
ImportOSSBucket	string	The OSS bucket to which the imported image belongs.	testEcsImport
Progress	string	The progress of the image copy task for an image that is being copied.	32%
SnapshotId	string	The snapshot ID.	s-bp17ot2q7x72ggtw****
ImportOSSObject	string	The OSS object to which the imported image belongs.	imageImport
Device	string	The device information of the disk, such as /dev/xvdb.	/dev/xvda
Size	string	The size of the disk. Unit: GiB.	60
RemainTime	integer	The remaining time of the image copy task for an image that is being copied. Unit: seconds.	233
Format	string	The image format.	qcow2
Encrypted	boolean	Note This parameter is in invitational preview.	true
Tags	object
Tag	array<object>	The list of tag key-value pairs of the image.
	object	The tag key-value pair of the image.
TagValue	string	The tag value of the image.	Oracle
TagKey	string	The tag key of the image.	DTS
IsPublic	boolean	Indicates whether the image is a public image. Public images include public images provided by Alibaba Cloud and custom images that you have published as community images. Valid values: true: The image is a public image. false: The image is not a public image.	false
ImageOwnerId	integer	The Alibaba Cloud account ID to which the image belongs. This parameter takes effect only when you query shared images or community images.	1234567890
LoginAsNonRootSupported	boolean	Indicates whether the image supports logon as a non-root user. Valid values: true: Supported. false: Not supported.	false
SupplierName	string	The verified enterprise name of the community image provider.	TestName
DetectionOptions	object	The image detection results.
Status	string	The status of the image detection task. Valid values: Processing: Detection is in progress. Finished: Detection is complete.	Processing
Items	object
Item	array<object>	The list of image detection items.
	object	The image detection item.
Name	string	The name of the image detection item.	Nvme
Value	string	The result of the image detection item.	Supported
RiskLevel	string	The risk level of the imported custom image detection item. This field is returned only when a risk exists. Valid values: High: Critical. Affects whether the instance can start successfully. We strongly recommend that you fix this issue. Medium: Important. Affects instance startup performance or instance configurations. We recommend that you optimize this.	High
RiskCode	string	The potential defect of the detection item.	NVMe.NotInstalled
Features	object	The feature-related attributes of the image.
NvmeSupport	string	Indicates whether the image supports NVMe. Valid values: supported: Supported. Instances created from this image support the NVMe protocol. unsupported: Not supported. Instances created from this image do not support the NVMe protocol.	supported
ImdsSupport	string	The metadata access mode of the image. Valid values: v1: When you create an ECS instance from this image, you cannot set the metadata access mode to security hardened mode. v2: When you create an ECS instance from this image, you can set the metadata access mode to security hardened mode. Instance metadata overview.	v2
CpuOnlineUpgrade	string	Indicates whether CPU hot-upgrade is supported. Valid values: supported: Supported. unsupported: Not supported.	supported
CpuOnlineDowngrade	string	Indicates whether CPU hot-downgrade is supported. Valid values: supported: Supported. unsupported: Not supported.	supported
MemoryOnlineUpgrade	string	Indicates whether memory hot-upgrade is supported. Valid values: supported: Supported. unsupported: Not supported.	unsupported
MemoryOnlineDowngrade	string	Indicates whether memory hot-downgrade is supported. Valid values: supported: Supported. unsupported: Not supported.	unsupported
LicenseType	string	The license type. This property determines the billable methods and activation logic for ECS instances created from this image. This parameter is meaningful only for Windows Server images. Valid values: Aliyun: Alibaba Cloud official license. Instances created from this image include Windows Server license fees and are automatically activated by Alibaba Cloud after startup. BYOL: Bring Your Own License. Instances created from this image do not include Windows Server license fees. After startup, the instances are not automatically activated and must be manually activated by using your own valid license.	BYOL

Examples

Success response

JSON format

{
  "PageSize": 1,
  "PageNumber": 1,
  "RequestId": "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
  "TotalCount": 1,
  "RegionId": "cn-hangzhou",
  "Images": {
    "Image": [
      {
        "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 数据中心版 64位中文版",
        "ImageId": "m-bp1g7004ksh0oeuc****",
        "OSType": "windows",
        "IsSubscribed": false,
        "ProductCode": "test000****",
        "Architecture": "x86_64",
        "BootMode": "BIOS",
        "DiskDeviceMappings": {
          "DiskDeviceMapping": [
            {
              "Type": "system",
              "ImportOSSBucket": "testEcsImport",
              "Progress": "32%",
              "SnapshotId": "s-bp17ot2q7x72ggtw****",
              "ImportOSSObject": "imageImport",
              "Device": "/dev/xvda",
              "Size": "60",
              "RemainTime": 233,
              "Format": "qcow2",
              "Encrypted": true
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "Oracle",
              "TagKey": "DTS"
            }
          ]
        },
        "IsPublic": false,
        "ImageOwnerId": 1234567890,
        "LoginAsNonRootSupported": false,
        "SupplierName": "TestName",
        "DetectionOptions": {
          "Status": "Processing",
          "Items": {
            "Item": [
              {
                "Name": "Nvme",
                "Value": "Supported",
                "RiskLevel": "High",
                "RiskCode": "NVMe.NotInstalled"
              }
            ]
          }
        },
        "Features": {
          "NvmeSupport": "supported",
          "ImdsSupport": "v2",
          "CpuOnlineUpgrade": "supported",
          "CpuOnlineDowngrade": "supported",
          "MemoryOnlineUpgrade": "unsupported",
          "MemoryOnlineDowngrade": "unsupported"
        },
        "LicenseType": "BYOL"
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidImageOwnerAlias.ValueNotSupported	The specified ImageOwnerAlias value is not supported.	The specified ImageOwnerAlias parameter is invalid.
400	InvalidParamter	Invalid Parameter.	The specified parameter is invalid.
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	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 number of specified tags exceeds the upper limit.
400	InvalidInstanceType.ValueNotSupported	The specified instance type %s does not exist. You can use the DescribeInstanceTypes API to query the available instance types.	The specified instance type does not exist. You can use the DescribeInstanceTypes API to query the available instance types.
400	InvalidFilterValue.NetworkType	The specified networkType value in the Filter is invalid.	The specified network type value in the filter is invalid.
400	InvalidOperation.ImageOwnerIdUnsupported	The parameter "ImageOwnerId" is not supported in this context, it is only valid when querying shared images or community images.	The ImageOwnerId parameter is not supported here and is valid only when querying shared images or community images.
400	InvalidImageOwnerAlias.PublicImageUnsupported	When querying images, the parameter ImageOwnerAlias should be others while specified parameter IsPublic is true.	When querying images, if the parameter IsPublic is true, the parameter ImageOwnerAlias must be others.
500	InternalError	The request processing has failed due to some unknown error.
403	CurrentAccount.NotSupportPublicImage	Public image is not supported for current account.	The current user cannot use public images.
404	InvalidFilterKey.NotFound	The specified Filter Key is not found.	The specified filter key is invalid.
404	InvalidFilterValue	The specified Filter Value is not valid.	The specified filter value is invalid.
404	InvalidUsage	The specified Usage is not valid.	The specified Usage parameter is invalid.
404	InvalidOSType	The specified OSType is not valid.	The specified OSType parameter is invalid.
404	InvalidArchitecture	The specified Architecture is not valid.	The Architecture parameter is invalid.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.