All Products
Search
Document Center

Elastic Compute Service:DescribeImages

Last Updated:Mar 19, 2024

Queries available images.

Operation 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 as well as the number of 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 the request parameter values in their 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.

Authorization information

There is currently no authorization information disclosed in the API.

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, only images in the Available state are returned if you do not specify this parameter. 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 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. To ensure future compatibility, we recommend that you use other parameters.
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 specify this parameter to query images of the specified image family.

This parameter is empty by default.

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 to return per page.

Maximum value: 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****
Tagobject []No

The tags list.

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
Filterobject []No

The list of 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 when 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
Imagesobject []

Details about the images.

CreationTimestring

The image creation time.

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

The image status. Valid values:

  • UnAvailable: The image is unavailable.
  • Available: The image is available.
  • Creating: The image is being created.
  • CreateFailed: The image cannot be created.
Available
ImageFamilystring

The image family name.

hangzhou-daily-update
Progressstring

The image creation progress. 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 image source. Valid values:

  • system: public images provided by Alibaba Cloud
  • self: your custom images
  • others: shared images from other Alibaba Cloud accounts, or community images published by other Alibaba Cloud accounts
  • marketplace: Alibaba Cloud Marketplace images.
self
IsSupportCloudinitboolean

Indicates whether the image supports cloud-init.

true
ImageVersionstring

The image version.

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 image description.

Archive log for Oracle
Sizeinteger

The image size. Unit: GiB.

60
ResourceGroupIdstring

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

rg-bp67acfmxazb4p****
Platformstring

The operating system.

Windows Server 2016
OSNameEnstring

The display name of the operating system in English.

Windows Server 2016 Data Center Edition 64bit Chinese Edition
ImageNamestring

The image name.

testImageName
OSNamestring

The display name of the operating system in Chinese.

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

The image ID.

m-bp1g7004ksh0oeuc****
OSTypestring

The type of the operating system. Valid values:

  • windows
  • linux
windows
IsSubscribedboolean

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

false
ProductCodestring

The product code of the Alibaba Cloud Marketplace 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
  • UEFI
Note When you use this parameter to change the boot mode of the image, specify a boot mode supported by the image. We recommend that you familiarize yourself with the boot modes supported by the specified image to ensure that instances that use this image can be started as expected.
BIOS
DiskDeviceMappingsobject []

The mappings between the disks and snapshots in the image.

Typestring

The image type.

system
ImportOSSBucketstring

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

testEcsImport
Progressstring

The progress of an image copy task.

32%
SnapshotIdstring

The snapshot ID.

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 disk size.

60
RemainTimeinteger

The remaining amount of time required for an image copy task. Unit: seconds.

233
Formatstring

The image format.

qcow2
Tagsobject []

The image tags.

TagValuestring

The value of tag N of the image.

Oracle
TagKeystring

The key of tag N 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 not publicly available.
false
ImageOwnerIdlong

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.

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 provider that published the community image.

TestName
DetectionOptionsobject

Details about the check performed on the image.

Statusstring

The status of the image check task. Valid values:

  • Processing: The image check task is in progress.
  • Finished: The image check task is completed.
Processing
Itemsobject []

The check items.

Namestring

The name of the check item.

Nvme
Valuestring

The result of the check item.

Supported
RiskLevelstring

The severity level of the risk that is detected on the check item of the imported custom image. If the system detects a risk on the check item, this parameter is returned. If the system does not detect a risk on the check item, this parameter is not returned.

Valid values:

  • High: The check item is a high-risk item that may affect the startup of the instance and mustbe fixed at your earliest convenience.
  • Medium: The check item is a medium-risk item that may affect the startup performance or configurations of the instance. We recommend that you fix this item.
High
RiskCodestring

The risk that is detected on the check item.

NVMe.NotInstallded
Featuresobject

The image attributes.

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 this image support NVMe.
  • unsupported: The image does not support the NVMe protocol. Instances created from this 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
2023-03-30The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 404 change
    delete Error Codes: 403
    delete Error Codes: 500
2021-07-26The Error code has changed. The response structure of the API has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    delete Error Codes: 400
    delete Error Codes: 403
    delete Error Codes: 404
    delete Error Codes: 500
Output ParametersThe response structure of the API has changed.