All Products
Search
Document Center

Elastic Compute Service:DescribeImages

Last Updated:Sep 29, 2024

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

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

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.
OperationAccess levelResource typeCondition keyAssociated operation
ecs:DescribeImagesget
  • Image
    acs:ecs:{#regionId}:{#accountId}:image/*
  • Image
    acs:ecs:{#regionId}:{#accountId}:image/{#imageId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
RegionIdstringYes

The region ID of the image. You can call the DescribeRegions operation to query the most recent region list.

cn-hangzhou
StatusstringNo

The status of the image. By default, if you do not specify this parameter, only images in the Available state are returned. 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 failed to be created.
  • Deprecated: The image is deprecated.

Default value: Available. You can specify multiple values for this parameter. Separate the values with commas (,).

Available
ImageIdstringNo

The image IDs.

m-bp1g7004ksh0oeuc****
ShowExpiredbooleanNo

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.
false
SnapshotIdstringNo

The ID of the snapshot used to create the custom image.

s-bp17ot2q7x72ggtw****
ImageNamestringNo

The image name.

testImageName
ImageFamilystringNo

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
ImageOwnerAliasstringNo

The image source. Valid values:

  • system: images that are provided by Alibaba Cloud and are not released in Alibaba Cloud Marketplace, which are different from public images in the Elastic Compute Service (ECS) console.

  • self: your custom images

  • others: shared images (images shared by other Alibaba Cloud accounts) and community images (publicly available custom images that are 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 IsPublic empty.
  • marketplace: images released by Alibaba Cloud or independent software vendors (ISVs) in the Alibaba Cloud Marketplace, which must be purchased together with ECS instances. Take note of the billing details of the images.

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
InstanceTypestringNo

The instance type for which the image can be used.

ecs.g5.large
IsSupportIoOptimizedbooleanNo

Specifies whether the image can be used on I/O optimized instances.

true
IsSupportCloudinitbooleanNo

Specifies whether the image supports cloud-init.

true
OSTypestringNo

The operating system type of the image. Valid values:

  • windows
  • linux
linux
ArchitecturestringNo

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
i386
PageNumberintegerNo

The page number to return.

Pages start from page 1.

Default value: 1.

1
PageSizeintegerNo

The number of entries per page.

Valid values: 1 to 100.

Default value: 10.

1
UsagestringNo

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 idle.
instance
DryRunbooleanNo

Specifies whether to perform only a dry run without performing the actual request.

  • true: performs only a dry run. The system checks whether your AccessKey pair is valid, whether RAM users are granted required permissions, and whether the required parameters are specified. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false: performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.

Default value: false.

false
ActionTypestringNo

The scenario in which the image is used. Valid values:

  • CreateEcs: instance creation
  • ChangeOS: replacement of the system disk or OS
CreateEcs
ResourceGroupIdstringNo

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****
Tagarray<object>No

The tags list.

objectNo

Information about the tag.

keystringNo

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
KeystringNo

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
ValuestringNo

The tag value of the image. Valid values of N: 1 to 20.

TestValue
valuestringNo

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
Filterarray<object>No

The list of filter conditions used to query resources.

objectNo

The filter conditions used to query resources.

KeystringNo

The key of the filter condition 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 as specified by the Filter.N.Value value.
CreationStartTime
ValuestringNo

The value of filter N used to query resources. When you specify this parameter, you must also specify Filter.N.Key. Make sure the time is in the yyyy-MM-ddTHH:mmZ format and in UTC.

2017-12-05T22:40Z
IsPublicbooleanNo

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 image types other than the community images type. The specific image types to be queried are determined by the ImageOwnerAlias value.

Default value: false.

false
ImageOwnerIdlongNo

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

ParameterTypeDescriptionExample
object
PageSizeinteger

The number of entries per page.

1
PageNumberinteger

The page number returned.

1
RequestIdstring

The request ID.

66189103-EDB2-43E2-BB60-BFF2B62F4EB8
TotalCountinteger

The total number of images.

1
RegionIdstring

The region ID of the image.

cn-hangzhou
Imagesarray<object>

The information of the images.

Imageobject

The information of the image.

CreationTimestring

The time when the image was created.

2019-11-15T06:07:05Z
Statusstring

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 failed to be created.
Available
ImageFamilystring

The name of the image family.

hangzhou-daily-update
Progressstring

The creation progress of the image. Unit: percent (%).

100%
IsCopiedboolean

Indicates whether the image is a copy of another image.

false
IsSupportIoOptimizedboolean

Indicates whether the image can be used on I/O optimized instances.

true
ImageOwnerAliasstring

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 from another Alibaba Cloud account or a community image published by another Alibaba Cloud account
  • marketplace: an Alibaba Cloud Marketplace image
self
IsSupportCloudinitboolean

Indicates whether the image supports cloud-init.

true
ImageVersionstring

The version of the image.

2
Usagestring

Indicates whether the image was used to create ECS instances. Valid values:

  • instance: The image was used to create one or more ECS instances.
  • none: The image was not used to create ECS instances.
none
IsSelfSharedstring

Indicates whether the custom image was shared to other Alibaba Cloud accounts.

true
Descriptionstring

The description of the image.

Archive log for Oracle
Sizeinteger

The size of the image. Unit: GiB.

Note If the image contains data disk snapshots, this parameter indicates only the size of the system disk snapshot contained in the image.
60
ResourceGroupIdstring

The ID of the resource group to which the image belongs.

rg-bp67acfmxazb4p****
Platformstring

The operating system platform.

Windows Server 2016
OSNameEnstring

The display name of the operating system in English.

Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageNamestring

The name of the image.

testImageName
OSNamestring

The display name of the operating system in Chinese.

Windows Server 2016 Datacenter Edition 64-bit (Simplified Chinese)
ImageIdstring

The ID of the image.

m-bp1g7004ksh0oeuc****
OSTypestring

The type of the operating system. Valid values:

  • windows
  • linux
windows
IsSubscribedboolean

Indicates whether you accepted the Terms of Service of the image service that corresponds to the product code.

false
ProductCodestring

The Alibaba Cloud Marketplace product code of the image.

test000****
Architecturestring

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
x86_64
BootModestring

The boot mode of the image. Valid values:

  • BIOS: Basic Input/Output System (BIOS)
  • UEFI: Unified Extensible Firmware Interface (UEFI)
  • UEFI-Preferred: BIOS and UEFI

For information about the image boot modes, see Image boot modes.

BIOS
DiskDeviceMappingsarray<object>

The mappings between disks and snapshots in the image.

DiskDeviceMappingobject

The mappings between the disks and snapshots in the image.

Typestring

The type of the image.

system
ImportOSSBucketstring

The Object Storage Service (OSS) bucket that contains the imported image file.

testEcsImport
Progressstring

The progress of the image copy task.

32%
SnapshotIdstring

The ID of the snapshot.

s-bp17ot2q7x72ggtw****
ImportOSSObjectstring

The OSS object that corresponds to the imported image file.

imageImport
Devicestring

The device name of the disk. Example: /dev/xvdb.

Note This parameter will be removed in the future. To ensure compatibility, we recommend that you use other parameters.
/dev/xvda
Sizestring

The size of the disk. Unit: GiB.

60
RemainTimeinteger

The remaining time of the image copy task. Unit: seconds.

233
Formatstring

The format of the image.

qcow2
Tagsarray<object>

The tags of the image.

Tagobject

Information about the tags.

TagValuestring

The tag value of the image.

Oracle
TagKeystring

The tag key of the image.

DTS
IsPublicboolean

Indicates whether the image is publicly available. Publicly available images include public images provided by Alibaba Cloud and custom images published as community images. Valid values:

  • true: The image is publicly available.
  • false: The image is publicly unavailable.
false
ImageOwnerIdlong

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
LoginAsNonRootSupportedboolean

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.
false
SupplierNamestring

The name of the supplier that published the community image.

TestName
DetectionOptionsobject

Details about the check performed on the image.

Statusstring

The state of the image check task. Valid values:

  • Processing
  • Finished
Processing
Itemsarray<object>

The check items.

Itemobject

Information about the check items.

Namestring

The name of the check item.

Nvme
Valuestring

The result of the check item.

Supported
RiskLevelstring

The severity of the risk that the check item of the imported custom image has. If the check item is at risk, this parameter is returned. If the check item is not at risk, this parameter is not returned.

Valid values:

  • High: The check item is a high-risk item that may affect the startup of the instance. We recommend that you handle the risk.
  • Medium: The check item is a medium-risk item that may affect the startup performance or configurations of the instance. We recommend that you handle the risk.
High
RiskCodestring

The risk that the check item may have.

NVMe.NotInstallded
Featuresobject

The attributes of the image.

NvmeSupportstring

Indicates whether the image supports the Non-Volatile Memory Express (NVMe) protocol. Valid values:

  • supported: The image supports the NVMe protocol. Instances created from the image also support the NVMe protocol.
  • unsupported: The image does not support the NVMe protocol. Instances created from the image do not support the NVMe protocol.
supported

Examples

Sample success responses

JSONformat

{
  "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 codeError codeError messageDescription
400InvalidImageOwnerAlias.ValueNotSupportedThe specified ImageOwnerAlias value is not supported.The specified ImageOwnerAlias parameter is invalid.
400InvalidParamterInvalid Parameter.The specified parameter is invalid.
400InvalidTag.MismatchThe 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.
400InvalidTagCountThe specified tags are beyond the permitted range.The number of specified tags exceeds the upper limit.
400InvalidInstanceType.ValueNotSupportedThe 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.
403CurrentAccount.NotSupportPublicImagePublic image is not supported for current account.The current user cannot use public images.
404InvalidFilterKey.NotFoundThe specified Filter Key is not found.The specified filter key is invalid.
404InvalidFilterValueThe specified Filter Value is not valid.The specified filter value is invalid.
404InvalidUsageThe specified Usage is not valid.The specified Usage parameter is invalid.
404InvalidOSTypeThe specified OSType is not valid.The specified OSType parameter is invalid.
404InvalidArchitectureThe specified Architecture is not valid.The Architecture parameter is invalid.
500InternalErrorThe 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 timeSummary of changesOperation
2024-09-26The Error code has changedView Change Details
2023-03-30The Error code has changedView Change Details
2021-07-26The Error code has changed. The response structure of the API has changedView Change Details