DescribeImages-阿里云帮助中心

Specify parameters such as ImageId, image usage scenario, and Filter to query the list of image resources you can use.

Operation description

The image resources you can query include your custom images, public images provided by Alibaba Cloud, Alibaba Cloud Marketplace images, and shared images actively shared with you by other Alibaba Cloud users.
Paged query is supported. The query results include the total number of usable image resources and the image resources on the current page. The default number of entries per page is 10.
When invoking the API through the Alibaba Cloud command-line interface (CLI), the values of request parameters of different data types must comply with format requirements. For more information, see CLI Parameter Format Description.
When querying official Alibaba Cloud images or shared images (where ImageOwnerAlias is set to system or others), RAM authentication rules are ignored for this request. 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 to which the image belongs. You can call DescribeRegions to view the latest list of Alibaba Cloud regions.	cn-hangzhou
Status	string	No	Queries images in the specified status. If this parameter is not configured, only images in the Available status are returned by default. Valid values: Creating: The image is being created. Waiting: The image is queued for multitasking. Available (default): The image is available for your use. UnAvailable: The image is unavailable for your use. CreateFailed: The image creation failed. Deprecated: The image has been deprecated. Default value: Available. This parameter supports multiple values separated by commas (,).	Available
ImageId	string	No	The image ID. Naming convention for image IDs Public images: Named based on the operating system version, architecture, language, and published 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 the letter `m`.	m-bp1g7004ksh0oeuc****
ShowExpired	boolean	No	Indicates whether subscription-based images have exceeded their usage period.	false
SnapshotId	string	No	The custom image created from a specific snapshot ID.	s-bp17ot2q7x72ggtw****
ImageName	string	No	The name of the image. Fuzzy search is supported.	testImageName
ImageFamily	string	No	The name of the image family. When querying images, you can use this parameter to filter images belonging to the specified image family. Default value: empty. Note For information about image families associated with official Alibaba Cloud images, see Overview of public images.	hangzhou-daily-update
ImageOwnerAlias	string	No	The source of the image. Valid values: system: Images provided by Alibaba Cloud that are not published on Alibaba Cloud Marketplace. This differs from the "public image" concept in the console. self: Your custom images. others: Includes shared images (images directly shared with you by other Alibaba Cloud users) and community images (custom images fully publicly shared by any Alibaba Cloud user). Note the following: To find community images, IsPublic must be true. To find shared images, IsPublic must be set to false or omitted. marketplace: Images published on Alibaba Cloud Marketplace by Alibaba Cloud or third-party ISVs, which must be purchased together with ECS instances. Please review the pricing details of Alibaba Cloud Marketplace images yourself. Default value: empty. Note An empty value returns results with ImageOwnerAlias values of system, self, and others.	self
InstanceType	string	No	Queries images that can be used with the specified instance type.	ecs.g5.large
IsSupportIoOptimized	boolean	No	Indicates whether the image can run on I/O optimized instances.	true
IsSupportCloudinit	boolean	No	Indicates 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 image resource list. Starting value: 1. Default value: 1.	1
PageSize	integer	No	The number of entries per page in a paged query. Maximum value: 100. Default value: 10.	10
Usage	string	No	Indicates whether the image is already running on an ECS instance. Valid values: instance: The image is in use by one or more ECS instances. none: The image is idle and not used by any ECS instance.	instance
DryRun	boolean	No	Specifies whether to perform a dry run of the request. true: Sends a dry run request without querying resource status. The system checks whether the AccessKey is valid, whether the Resource Access Management (RAM) user is authorized, and whether all required parameters are specified. If the check fails, an error is returned. If the check passes, the error code DryRunOperation is returned. false: Sends a normal request. After the check passes, an HTTP 2XX status code is returned and the resource status is queried directly. Default value: false.	false
ActionType	string	No	The scenario in which the image will be used. Valid values: CreateEcs (default): Create an instance. ChangeOS: Replace the system disk or change the operating system.	CreateEcs
ResourceGroupId	string	No	The ID of the enterprise resource group to which the custom image belongs. When using this parameter to filter resources, the number of resources 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	Tag information.
key	string	No	The tag key of the image. Note This parameter will soon be deprecated. To improve compatibility, we recommend that you use the `Tag.N.Key` parameter instead.	null
Key	string	No	The tag key of the image. Valid values of N: 1 to 20. When you use one tag to filter resources, the number of resources retrieved under this tag cannot exceed 1,000. When you use multiple tags to filter resources, the number of resources that are attached with all specified tags cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources API to query the resources.	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 soon be deprecated. To improve compatibility, we recommend that you use the `Tag.N.Value` parameter instead.	null
Filter	array<object>	No	A list of filter conditions for querying resources.
	object	No	A filter condition for querying resources.
Key	string	No	The filter key used when querying resources. Valid values: If this parameter is set to `CreationStartTime`, you can query resources created after the specified time point (`Filter.N.Value`). If this parameter is set to `CreationEndTime`, you can query resources created before the specified time point (`Filter.N.Value`). If this parameter is set to `NetworkType`, you can query resources of the specified network type. If this parameter is set to any of `CpuOnlineUpgrade`, `CpuOnlineDowngrade`, `MemoryOnlineUpgrade`, or `MemoryOnlineDowngrade`, you can query the hot-swapping support status of CPU or memory for the specified image. Default Value: null.	CreationStartTime
Value	string	No	The filter value used when querying resources. When (`Filter.N.Key`) is `CreationStartTime` or `CreationEndTime`, the format is `yyyy-MM-ddTHH:mmZ` in UTC+0 time zone. When (`Filter.N.Key`) is `NetworkType`, valid values include `vpc`, `classic`, etc. When (`Filter.N.Key`) is `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 this parameter is set to true, ImageOwnerAlias must be set to others. false: Queries other image types excluding community images, depending on the value of the ImageOwnerAlias parameter. Default Value: false.	false
ImageOwnerId	integer	No	The Alibaba Cloud account ID to which the image belongs. This parameter takes effect only when you query shared images and community images.	20169351435666****

Response elements

Element	Type	Description	Example
	object
PageSize	integer	Number of entries on the current page.	1
PageNumber	integer	Current page number.	1
RequestId	string	Request ID.	66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCount	integer	Total number of images.	1
RegionId	string	The region ID to which the image belongs.	cn-hangzhou
Images	object
Image	array<object>	Collection of image information.
	array<object>	Image information.
CreationTime	string	The creation time of the image.	2019-11-15T06:07:05Z
Status	string	The status of the image. Valid values: UnAvailable: unavailable. Available: active. Creating: being created. CreateFailed: creation failed.	Available
ImageFamily	string	The image family name.	hangzhou-daily-update
Progress	string	The completion progress of the image, expressed as a percentage.	100%
IsCopied	boolean	Indicates whether the image is copied.	false
IsSupportIoOptimized	boolean	Indicates whether the image can run on an I/O optimized instance.	true
ImageOwnerAlias	string	Source of the image. Possible values: system: Public images provided by Alibaba Cloud. self: Custom images you created. others: Shared images or community images provided by other Alibaba Cloud users. marketplace: Images provided by Alibaba Cloud Marketplace.	self
IsSupportCloudinit	boolean	Indicates whether Cloud Init is supported.	true
ImageVersion	string	Image version.	2
Usage	string	The resource type that has a reference relationship with the image. Valid values: instance: one or more ECS instances have been created. none: no ECS instance has been created.	none
IsSelfShared	string	Indicates whether the custom image has been shared with other users.	true
Description	string	Description.	Archive log for Oracle
Size	integer	The size of the image, in GiB. Important If the image includes a data disk, this parameter indicates 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 image name.	testImageName
OSName	string	The Chinese display name of the operating system.	Windows Server 2016 数据中心版 64位中文版
ImageId	string	The image ID.	m-bp1g7004ksh0oeuc****
OSType	string	Operating system type. Valid values: windows linux	windows
IsSubscribed	boolean	Indicates whether you have subscribed to the service terms of the product corresponding to the image's product code.	false
ProductCode	string	The product identifier of the Alibaba Cloud Marketplace image.	test000****
Architecture	string	The system architecture type 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 Modes.	BIOS
DiskDeviceMappings	object
DiskDeviceMapping	array<object>	A collection of mappings between disks and snapshots in the image.
	object	The mapping between a disk and a snapshot in the image.
Type	string	The image Type.	system
ImportOSSBucket	string	The OSS bucket to which the imported image belongs.	testEcsImport
Progress	string	For an image that is being copied, the progress of the copy Job is returned.	32%
SnapshotId	string	The snapshot ID.	s-bp17ot2q7x72ggtw****
ImportOSSObject	string	The OSS object to which the imported image belongs.	imageImport
Device	string	The disk Device Information, such as /dev/xvdb.	/dev/xvda
Size	string	The disk size. Unit: GiB.	60
RemainTime	integer	For an image that is being copied, the remaining time of the copy job is returned, in seconds.	233
Format	string	The image format.	qcow2
Encrypted	boolean	This parameter is in invitational preview.	true
Tags	object
Tag	array<object>	A list of tag key-value pairs for the image.
	object	The tag key-value pair information 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 public. Public images include public images provided by Alibaba Cloud and your custom images that have been published as community images. Valid values: true: Public image. false: Non-public image.	false
ImageOwnerId	integer	The Alibaba Cloud account ID to which the image belongs. This parameter takes effect only when querying shared images and community images.	1234567890
LoginAsNonRootSupported	boolean	Indicates whether the current image supports logon by non-root users. Valid values: true: Supported. false: Not supported.	false
SupplierName	string	The name of the enterprise that provides authentication for the community image.	TestName
DetectionOptions	object	Detection-related results for the image.
Status	string	The status of the image detection job. Possible values: Processing: Detection is in progress. Finished: Detection is complete.	Processing
Items	object
Item	array<object>	The list of check items for image detection.
	object	A check item for image detection.
Name	string	Name of the image check item.	Nvme
Value	string	The result of the image detection check item.	Supported
RiskLevel	string	Indicates whether the imported custom image check item poses a threat. This field is returned only if a threat exists. Possible threat levels: High: Critical. Affects whether the instance can start successfully. Strongly recommended to fix. Medium: Important. Affects instance startup performance or instance configuration. Optimization is recommended.	High
RiskCode	string	The bug that may exist in the check item.	NVMe.NotInstalled
Features	object	Attributes related to image features.
NvmeSupport	string	Indicates whether the image supports NVMe. Possible 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. Possible values: v1: When you create an ECS instance from this image, you cannot set the metadata access mode to "Hardened Mode Only." v2: When you create an ECS instance from this image, you can set the metadata access mode to "Hardened Mode Only."	v2
CpuOnlineUpgrade	string	Indicates whether CPU hot upgrade is supported. Possible values: supported: Supported. unsupported: Not supported.	supported
CpuOnlineDowngrade	string	Indicates whether CPU hot downgrade is supported. Possible values: supported: Supported. unsupported: Not supported.	supported
MemoryOnlineUpgrade	string	Indicates whether memory hot upgrade is supported. Possible values: supported: Supported. unsupported: Not supported.	unsupported
MemoryOnlineDowngrade	string	Indicates whether memory hot decrease the quota is supported. Possible values: supported: Supported. unsupported: Not supported.	unsupported
LicenseType	string	The license type. This property determines the billing method and activation logic for ECS instances created from this image, and is relevant only for Windows Server images. Valid values: Aliyun: Official Alibaba Cloud license. Instances created from this image include the Windows Server license fee and are automatically activated by Alibaba Cloud after startup. BYOL: Bring Your Own License. Instances created from this image do not include the Windows Server license fee and are not automatically activated after startup; you must manually activate them 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.