Queries available images.

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 and 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 request parameter values of different data types in 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. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

ParameterTypeRequiredExampleDescription
ActionStringYesDescribeImages

The operation that you want to perform. Set the value to DescribeImages.

RegionIdStringYescn-hangzhou

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

StatusStringNoAvailable

The state 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 cannot be created.
  • Deprecated: The image is discontinued.

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

ImageIdStringNom-bp1g7004ksh0oeuc****

The ID of the image.

ShowExpiredBooleanNofalse

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.
SnapshotIdStringNos-bp17ot2q7x72ggtw****

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

ImageNameStringNotestImageName

The name of the image.

ImageFamilyStringNohangzhou-daily-update

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.

ImageOwnerAliasStringNoself

The source of the image. 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. Take note of the following items:
    • To query community images, you must set the IsPublic parameter to true.
    • To query shared images, you must set the IsPublic parameter to false or leave the IsPublic parameter empty.
  • marketplace: Alibaba Cloud Marketplace images. If Alibaba Cloud Marketplace images are returned in the response, you can use the images without subscription. You must pay attention to the billing details of Alibaba Cloud Marketplace images.

This parameter is empty by default, which indicates that your custom images, public images provided by Alibaba Cloud, shared images from other Alibaba Cloud accounts, and community images published by other Alibaba Cloud accounts are queried.

InstanceTypeStringNoecs.g5.large

The instance type for which the image can be used.

IsSupportIoOptimizedBooleanNotrue

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

IsSupportCloudinitBooleanNotrue

Indicates whether cloud-init is supported by the image.

OSTypeStringNolinux

The operating system type of the image. Valid values:

  • windows
  • linux
ArchitectureStringNoi386

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
PageNumberIntegerNo1

The number of the page to return.

Page start from page 1.

Default value: 1.

PageSizeIntegerNo1

The number of entries to return on each page.

Maximum value: 100.

Default value: 10.

UsageStringNoinstance

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 not in use.
DryRunBooleanNofalse

Specifies whether to check the validity of the request without actually making the request. Valid values:

  • true: The validity of the request is checked but the request is not made. Check items include whether your AccessKey pair is valid, whether RAM users are granted required permissions, 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: The validity of the request is checked. If the check succeeds, a 2XX HTTP status code is returned, and the request is made.

Default value: false.

ActionTypeStringNoCreateEcs

The scenario in which to use the image. Default value: CreateEcs. Valid values:

  • CreateEcs: instance creation
  • ChangeOS: replacement of the system disk or operating system
ResourceGroupIdStringNorg-bp67acfmxazb4p****

The ID of the resource group to which the custom image belongs. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group can be displayed in the response.

Note Resources in the default resource group are displayed in the response regardless of how this parameter is set.
Tag.N.keyStringNonull

The key of tag N of the image.

Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use the Tag.N.Key parameter.
Tag.N.KeyStringNoTestKey

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

If a single tag is specified to query resources, up to 1,000 resources that have this tag added can be displayed in the response. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added can be displayed in the response. To query more than 1,000 resources that have specified tags added, call the ListTagResources operation.

Tag.N.ValueStringNoTestValue

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

Tag.N.valueStringNonull

The value of tag N of the image.

Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use the Tag.N.Value parameter.
Filter.N.KeyStringNoCreationStartTime

The key of filter N 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 parameter.
  • If you set this parameter to CreationEndTime, you can query the resources that were created before the point in time specified by the Filter.N.Value parameter.
Filter.N.ValueStringNo2017-12-05T22:40Z

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

IsPublicBooleanNofalse

Specifies whether to query published community images. Valid values:

  • true: queries published community images. When you set this parameter to true, you must set the ImageOwnerAlias parameter to others.
  • false: queries image types other than community images. The specific image types to be queried are determined by the ImageOwnerAlias parameter.

Default value: false.

ImageOwnerIdLongNo1234567890

The ID of the Alibaba Cloud account to which the image belongs. This parameter is valid only when you query shared images or community images.

Response parameters

ParameterTypeExampleDescription
PageSizeInteger1

The number of entries returned per page.

PageNumberInteger1

The number of the returned page.

RequestIdString66189103-EDB2-43E2-BB60-BFF2B62F4EB8

The ID of the request.

TotalCountInteger1

The total number of images.

RegionIdStringcn-hangzhou

The region ID of the image.

ImagesArray of Image

Details about the images.

Image
CreationTimeString2019-11-15T06:07:05Z

The time when the image was created.

StatusStringAvailable

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 cannot be created.
ImageFamilyStringhangzhou-daily-update

The name of the image family.

ProgressString100%

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

IsCopiedBooleanfalse

Indicates whether the image is a copy of another image.

IsSupportIoOptimizedBooleantrue

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

ImageOwnerAliasStringself

The source of the image. 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
IsSupportCloudinitBooleantrue

Indicates whether the image supports cloud-init.

ImageVersionString2

The version of the image.

UsageStringnone

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

  • instance: The image has been used to create one or more ECS instances.
  • none: The image has not been used to create ECS instances.
IsSelfSharedStringtrue

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

DescriptionStringArchive log for Oracle

The description of the image.

SizeInteger60

The size of the image. Unit: GiB.

ResourceGroupIdStringrg-bp67acfmxazb4p****

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

PlatformStringWindows Server 2016

The operating system.

OSNameEnStringWindows Server 2016 Data Center Edition 64bit Chinese Edition

The display name of the operating system in English.

ImageNameStringtestImageName

The name of the image.

OSNameStringWindows Server 2016 Datacenter 64-bit (Simplified Chinese)

The display name of the operating system in Chinese.

ImageIdStringm-bp1g7004ksh0oeuc****

The ID of the image.

OSTypeStringwindows

The type of the operating system. Valid values:

  • windows
  • linux
IsSubscribedBooleanfalse

Indicates whether you have subscribed to the image that corresponds to the specified product code.

ProductCodeStringtest000****

The product code of the Alibaba Cloud Marketplace image.

ArchitectureStringx86_64

The architecture of the image. Valid values:

  • i386
  • x86_64
  • arm64
BootModeStringBIOS

The boot mode of the image. Valid values:

  • BIOS
  • UEFI
Note You must be aware of the boot modes supported by the specified image. When you use this parameter to change the boot mode of the image, specify a boot mode supported by the image to ensure that instances that use this image can start as expected.
DiskDeviceMappingsArray of DiskDeviceMapping

The mappings between disks and snapshots that belong to the image.

DiskDeviceMapping
TypeStringsystem

The type of the image.

ImportOSSBucketStringtestEcsImport

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

ProgressString32%

The progress of an image copy task.

SnapshotIdStrings-bp17ot2q7x72ggtw****

The ID of the snapshot.

ImportOSSObjectStringimageImport

The OSS object that corresponds to the imported image file.

DeviceString/dev/xvda

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.
SizeString60

The size of the disk.

RemainTimeInteger233

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

FormatStringqcow2

The format of the image.

TagsArray of Tag

The tags of the image.

Tag
TagValueStringOracle

The tag value of the image.

TagKeyStringDTS

The tag key of the image.

IsPublicBooleanfalse

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.
ImageOwnerIdLong1234567890

The ID of the Alibaba Cloud account to which the image belongs. This parameter is valid only when you query shared images or community images.

LoginAsNonRootSupportedBooleanfalse

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.
SupplierNameStringTestName

The name of the supplier that certified the community image.

DetectionOptionsObject

Details about the check performed on the image.

StatusStringProcessing

The state of the image check task. Valid values:

  • Processing: The image check task is in progress.
  • Finished: The image check task is completed.
ItemsArray of Item

The check items.

Item
NameStringNvme

The name of the check item.

ValueStringSupported

The result of the check item.

RiskLevelStringHigh

Indicates the severity 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. We strongly recommended 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.
RiskCodeStringNVMe.NotInstallded

The risk that is detected on the check item.

FeaturesObject

The attributes of the image.

NvmeSupportStringsupported

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

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

Examples

Sample requests

http(s)://ecs.aliyuncs.com/?Action=DescribeImages
&RegionId=cn-hangzhou
&PageNumber=1
&PageSize=1
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeImagesResponse>
    <TotalCount>1</TotalCount>
    <PageSize>1</PageSize>
    <RequestId>66189103-EDB2-43E2-BB60-BFF2B62F4EB8</RequestId>
    <PageNumber>1</PageNumber>
    <Images>
        <Image>
            <ImageOwnerAlias>self</ImageOwnerAlias>
            <IsSelfShared>true</IsSelfShared>
            <Description>Archive log for Oracle</Description>
            <Platform>Windows Server 2016</Platform>
            <ResourceGroupId>rg-bp67acfmxazb4p****</ResourceGroupId>
            <Size>60</Size>
            <IsSubscribed>false</IsSubscribed>
            <BootMode>BIOS</BootMode>
            <OSName>Windows Server 2016 Datacenter 64-bit (Simplified Chinese)</OSName>
            <IsPublic>false</IsPublic>
            <ImageId>m-bp1g7004ksh0oeuc****</ImageId>
            <DetectionOptions/>
            <Features>
                <NvmeSupport>supported</NvmeSupport>
            </Features>
            <OSNameEn>Windows Server 2016 Data Center Edition 64bit Chinese Edition</OSNameEn>
            <Tags>
                <Tag>
                    <TagKey>DTS</TagKey>
                    <TagValue>Oracle</TagValue>
                </Tag>
            </Tags>
            <LoginAsNonRootSupported>false</LoginAsNonRootSupported>
            <Status>Available</Status>
            <Progress>100%</Progress>
            <Usage>none</Usage>
            <Architecture>x86_64</Architecture>
            <ProductCode>test000****</ProductCode>
            <IsCopied>false</IsCopied>
            <ImageFamily>hangzhou-daily-update</ImageFamily>
            <IsSupportIoOptimized>true</IsSupportIoOptimized>
            <IsSupportCloudinit>true</IsSupportCloudinit>
            <ImageName>testImageName</ImageName>
            <DiskDeviceMappings>
                <DiskDeviceMapping>
                    <SnapshotId>s-bp17ot2q7x72ggtw****</SnapshotId>
                    <Type>system</Type>
                    <Progress>32%</Progress>
                    <Format>qcow2</Format>
                    <Device>/dev/xvda</Device>
                    <Size>60</Size>
                    <ImportOSSBucket>testEcsImport</ImportOSSBucket>
                    <ImportOSSObject>imageImport</ImportOSSObject>
                </DiskDeviceMapping>
            </DiskDeviceMappings>
            <ImageVersion>2</ImageVersion>
            <OSType>windows</OSType>
            <CreationTime>2019-11-15T06:07:05Z</CreationTime>
        </Image>
    </Images>
    <RegionId>cn-hangzhou</RegionId>
</DescribeImagesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalCount" : 1,
  "PageSize" : 1,
  "RequestId" : "66189103-EDB2-43E2-BB60-BFF2B62F4EB8",
  "PageNumber" : 1,
  "Images" : {
    "Image" : [ {
      "ImageOwnerAlias" : "self",
      "IsSelfShared" : "true",
      "Description" : "Archive log for Oracle",
      "Platform" : "Windows Server 2016",
      "ResourceGroupId" : "rg-bp67acfmxazb4p****",
      "Size" : 60,
      "IsSubscribed" : false,
      "BootMode" : "BIOS",
      "OSName": "Windows Server 2016 Datacenter Edition 64-bit (Simplified Chinese)",
      "IsPublic" : false,
      "ImageId" : "m-bp1g7004ksh0oeuc****",
      "DetectionOptions" : { },
      "Features" : {
        "NvmeSupport" : "supported"
      },
      "OSNameEn" : "Windows Server 2016 Data Center Edition 64bit Chinese Edition",
      "Tags" : {
        "Tag" : [ {
          "TagKey" : "DTS",
          "TagValue" : "Oracle"
        } ]
      },
      "LoginAsNonRootSupported" : false,
      "Status" : "Available",
      "Progress" : "100%",
      "Usage" : "none",
      "Architecture" : "x86_64",
      "ProductCode" : "test000****",
      "IsCopied" : false,
      "ImageFamily" : "hangzhou-daily-update",
      "IsSupportIoOptimized" : true,
      "IsSupportCloudinit" : true,
      "ImageName" : "testImageName",
      "DiskDeviceMappings" : {
        "DiskDeviceMapping" : [ {
          "SnapshotId" : "s-bp17ot2q7x72ggtw****",
          "Type" : "system",
          "Progress" : "32%",
          "Format" : "qcow2",
          "Device" : "/dev/xvda",
          "Size" : "60",
          "ImportOSSBucket" : "testEcsImport",
          "ImportOSSObject" : "imageImport"
        } ]
      },
      "ImageVersion" : "2",
      "OSType" : "windows",
      "CreationTime" : "2019-11-15T06:07:05Z"
    } ]
  },
  "RegionId" : "cn-hangzhou"
}

Error codes

HTTP status codeError codeError messageDescription
400InvalidImageOwnerAlias.ValueNotSupportedThe specified ImageOwnerAlias value is not supported.The error message returned because the specified ImageOwnerAlias parameter is invalid.
400InvalidParamterInvalid ParameterThe error message returned because a specified parameter is invalid.
400InvalidTag.MismatchThe specified Tag.n.Key and Tag.n.Value are not match.The error message returned because the specified Tag.N.Key parameter does not correspond to the specified Tag.N.Value parameter.
400InvalidTagCountThe specified tags are beyond the permitted range.The error message returned because the number of specified tags has exceeded the upper limit.
400InvalidInstanceType.ValueNotSupportedThe specified InstanceType does not exist or beyond the permitted range.The error message returned because the specified instance type does not exist or because you are not authorized to manage instances of the specified instance type.
404InvalidUsageThe specifed Usage is not validThe error message returned because the specified Usage parameter is invalid.
404InvalidOSTypeThe specifed OSType is not validThe error message returned because the specified OSType parameter is invalid.
404InvalidArchitectureThe specifed Architecture is not validThe error message returned because the specified architecture does not exist.
500InternalErrorThe request processing has failed due to some unknown error.The error message returned because an internal error has occurred. Try again later. If the error persists, submit a ticket.

For a list of error codes, visit the API Error Center.