DescribeImageFromFamily -

Queries the latest available image in a specific image family.

Usage notes

If no available image exists in a specific image family, the response is empty.

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

Parameter	Type	Required	Example	Description
Action	String	Yes	DescribeImageFromFamily	The operation that you want to perform. Set the value to DescribeImageFromFamily.
RegionId	String	Yes	cn-hangzhou	The region ID of the image. You can call the DescribeRegions operation to query the most recent region list.
ImageFamily	String	Yes	hangzhou-daily-update	The name of the image family. You can configure image families for custom images, public images, community images, and shared images. For more information, see Overview.

Response parameters

Parameter	Type	Example	Description
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The request ID.
Image	Object		The image information.
CreationTime	String	2018-01-10T01:01:10Z	The time when the image was created.
Status	String	Available	The status of the image. Valid values: UnAvailable Available Creating CreateFailed
ImageFamily	String	testImageFamily	The name of the image family.
Progress	String	100	The image creation progress. Unit: percent (%).
IsCopied	Boolean	false	Indicates whether the image is a copy of another image.
IsSupportIoOptimized	Boolean	true	Indicates whether the image can be used on I/O optimized instances.
ImageOwnerAlias	String	self	The alias of the image owner. Valid values: system: public images provided by Alibaba Cloud self: your custom images others: shared images from other Alibaba Cloud accounts marketplace: Alibaba Cloud Marketplace images
IsSupportCloudinit	Boolean	true	Indicates whether the image supports cloud-init.
ImageVersion	String	2	The version of the image.
Usage	String	none	Indicates whether the image is used to create ECS instances. Valid values: instance: The image is used to create one or more ECS instances. none: The image is not used to create ECS instances.
IsSelfShared	String	true	Indicates whether the custom image was shared to other Alibaba Cloud accounts.
Description	String	testDescription	The description.
Size	Integer	80	The image size. Unit: GiB.
Platform	String	Aliyun	The operating system platform.
ImageName	String	testImageName	The name of the image.
OSName	String	Alibaba Cloud Linux 2.1903	The display name in Chinese of the operating system.
ImageId	String	m-bp1g7004ksh0oeuc****	The image ID.
OSType	String	linux	The type of the operating system. Valid values: windows linux
IsSubscribed	Boolean	false	Indicates whether you have subscribed to the service terms of the image product corresponding to the image product code.
ProductCode	String	jxsc00****	The product code of the Alibaba Cloud Marketplace image.
Architecture	String	x86_64	The architecture of the image. Valid values: i386 x86_64
DiskDeviceMappings	Array of DiskDeviceMapping		The mappings between disks and snapshots in the image.
DiskDeviceMapping
Type	String	custom	The type of the image.
ImportOSSBucket	String	testEcsImport	The Object Storage Service (OSS) bucket that contains the imported image file.
SnapshotId	String	s-bp17ot2q7x72ggtw****	The snapshot ID.
ImportOSSObject	String	imageImport	The OSS object corresponding to the imported image file.
Size	String	80	The size of the disk. Unit: GiB.
Device	String	/dev/xvdb	The device name of the disk. Example: /dev/xvdb. Note This parameter will be deprecated. We recommend that you use other parameters to ensure compatibility.
Format	String	qcow2	The format of the image.
Tags	Array of Tag		The tags of the image.
Tag
TagValue	String	TestValue	The tag value of the custom image.
TagKey	String	TestKey	The tag key of the custom image.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeImageFromFamily
&RegionId=cn-hangzhou
&ImageFamily=as-hangzhou-game-01
&<Common request parameters>

Sample success responses

XML format

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

<DescribeImageFromFamilyResponse>
    <RequestId>E39053A7-C3E6-41FA-8F8D-F5BD8063E61C</RequestId>
    <Image>
        <ImageOwnerAlias>self</ImageOwnerAlias>
        <Status>Available</Status>
        <Progress/>
        <Usage/>
        <Description>testDescription</Description>
        <IsSelfShared/>
        <Architecture>x86_64</Architecture>
        <Platform>CentOS</Platform>
        <ProductCode/>
        <Size>40</Size>
        <IsSubscribed>false</IsSubscribed>
        <IsCopied>false</IsCopied>
        <ImageFamily>testImageFamily</ImageFamily>
        <OSName>CentOS 8.0 64位</OSName>
        <IsSupportIoOptimized>true</IsSupportIoOptimized>
        <IsSupportCloudinit>true</IsSupportCloudinit>
        <ImageName>testImageName</ImageName>
        <DiskDeviceMappings>
            <DiskDeviceMapping>
                <SnapshotId>s-bp1ejhb4r1lyu55t****</SnapshotId>
                <Type>system</Type>
                <Format/>
                <Size>40</Size>
                <Device>/dev/xvda</Device>
                <ImportOSSBucket/>
                <ImportOSSObject/>
            </DiskDeviceMapping>
        </DiskDeviceMappings>
        <ImageVersion/>
        <OSType>linux</OSType>
        <ImageId>m-bp1ejhb4r1lyu55t****</ImageId>
        <CreationTime>2020-03-17T06:19:19Z</CreationTime>
        <Tags>
        </Tags>
    </Image>
</DescribeImageFromFamilyResponse>

JSON format

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

{
  "RequestId" : "E39053A7-C3E6-41FA-8F8D-F5BD8063E61C",
  "Image" : {
    "ImageOwnerAlias" : "self",
    "Status" : "Available",
    "Progress" : "",
    "Usage" : "",
    "Description" : "testDescription",
    "IsSelfShared" : "",
    "Architecture" : "x86_64",
    "Platform" : "CentOS",
    "ProductCode" : "",
    "Size" : 40,
    "IsSubscribed" : false,
    "IsCopied" : false,
    "ImageFamily" : "testImageFamily",
    "OSName" : "CentOS 8.0 64位",
    "IsSupportIoOptimized" : true,
    "IsSupportCloudinit" : true,
    "ImageName" : "testImageName",
    "DiskDeviceMappings" : {
      "DiskDeviceMapping" : [ {
        "SnapshotId" : "s-bp1ejhb4r1lyu55t****",
        "Type" : "system",
        "Format" : "",
        "Size" : "40",
        "Device" : "/dev/xvda",
        "ImportOSSBucket" : "",
        "ImportOSSObject" : ""
      } ]
    },
    "ImageVersion" : "",
    "OSType" : "linux",
    "ImageId" : "m-bp1ejhb4r1lyu55t****",
    "CreationTime" : "2020-03-17T06:19:19Z",
    "Tags" : {
      "Tag" : [ ]
    }
  }
}

Error codes

HTTP status code	Error code	Error message	Description
404	InvalidRegionId.NotFound	The RegionId provided does not exist.	The RegionId is not found.

For a list of error codes, see Service error codes.