Queries available images. When you call this operation, you can specify parameters, such as ImageId, ImageFamily, and InstanceType, in the request.
Operation description
Usage notes
- 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 is a paginated query. The response contains the total number of available images and the 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 the required formats. For more information, see Parameter formats.
- If you set ImageOwnerAlias to system or others when you call the DescribeImages operation to query public images that are provided by Alibaba Cloud or shared images, Resource Access Management (RAM) policies are ignored in the request. For more information, see RAM authorization.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action
policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level,
All Resources
is used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
Operation | Access level | Resource type | Condition key | Associated operation |
---|---|---|---|---|
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 the DescribeRegions operation to query the most recent region list. | cn-hangzhou |
Status | string | No | The status 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 (,). | Available |
ImageId | string | No | The image IDs. | 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. | testImageName |
ImageFamily | string | No | 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. Note
For information about image families that are associated with Alibaba Cloud official images, see Overview of public images.
| hangzhou-daily-update |
ImageOwnerAlias | string | No | The image source. Valid values:
This parameter is empty by default. Note
By default, this parameter is empty, which indicates that the following images are queried: public images provided by Alibaba Cloud, custom images in your repository, shared images from other Alibaba Cloud accounts, and community images that are published by other Alibaba Cloud accounts.
| self |
InstanceType | string | No | The instance type for which the image can be used. | ecs.g5.large |
IsSupportIoOptimized | boolean | No | Specifies whether the image can be used 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:
| linux |
Architecture | string | No | The architecture of the image. Valid values:
| i386 |
PageNumber | integer | No | The page number to return. Pages start from page 1. Default value: 1. | 1 |
PageSize | integer | No | The number of entries per page. Valid values: 1 to 100. Default value: 10. | 1 |
Usage | string | No | Specifies whether the image is running on an Elastic Compute Service (ECS) instance. Valid values:
| instance |
DryRun | boolean | No | Specifies whether to perform only a dry run without performing the actual request.
Default value: false. | false |
ActionType | string | No | The scenario in which the image is used. Valid values:
| CreateEcs |
ResourceGroupId | string | No | The ID of the resource group to which the custom image belongs. If you specify this parameter to query resources, up to 1,000 resources that belong to the specified resource group can be returned. Note
Resources in the default resource group are displayed in the response regardless of whether you specify this parameter.
| rg-bp67acfmxazb4p**** |
Tag | array<object> | No | The tags list. | |
object | No | Information about the tag. | ||
key | string | No | The image tag key. ** This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure future compatibility.`` | null |
Key | string | No | The tag N key of the image. Valid values of N: 1 to 20. Up to 1,000 resources that match the specified tags can be returned in the response. To query more than 1,000 resources that match the specified tags, 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 custom image. Note
This parameter will be removed in the future. To ensure future compatibility, we recommend that you use the Tag.N.Value parameter.
| null |
Filter | array<object> | No | The list of filter conditions used to query resources. | |
object | No | The filter conditions used to query resources. | ||
Key | string | No | The key of the filter condition used to query resources. Valid values:
| CreationStartTime |
Value | string | No | The value of filter N used to query resources. When you specify this parameter, you must also specify | 2017-12-05T22:40Z |
IsPublic | boolean | No | Specifies whether to query published community images. Valid values:
Default value: false. | false |
ImageOwnerId | long | No | The ID of the Alibaba Cloud account to which the image belongs. This parameter takes effect only if you query shared images or community images. | 1234567890 |
Response parameters
Examples
Sample success responses
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 Datacenter Edition 64-bit (Simplified Chinese)\n",
"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"
}
]
},
"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.NotInstallded"
}
]
}
},
"Features": {
"NvmeSupport": "supported"
}
}
]
}
}
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 InstanceType does not exist or beyond the permitted range. | The specified instance type does not exist or you are not authorized to manage instances of this instance type. |
400 | InvalidFilterValue.NetworkType | The specified networkType value in the Filter is invalid. | The specified network type value in the filter is invalid. |
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. |
500 | InternalError | The request processing has failed due to some unknown error. | An internal error has occurred. Try again later. |
For a list of error codes, visit the Service error codes.
Change history
Change time | Summary of changes | Operation |
---|---|---|
2024-12-05 | The Error code has changed. The response structure of the API has changed | View Change Details |
2024-09-26 | The Error code has changed | View Change Details |
2023-03-30 | The Error code has changed | View Change Details |
2021-07-26 | The Error code has changed. The response structure of the API has changed | View Change Details |