All Products
Search
Document Center

Elastic Compute Service:DescribeImageFromFamily

Last Updated:Sep 29, 2024

You can call this operation to query available custom images that are newly created in a specific image family.

Operation description

Description

  • This API operation only returns the available custom images that are newly created in the specified image family. Public images, Alibaba Cloud Marketplace images, community images, or shared images are not queried.
  • If no available custom images exist in the specified 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.

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:DescribeImageFromFamilyget
  • All Resources
    *
    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
ImageFamilystringYes

The name of the image family. The name must be 2 to 128 characters in length and can contain letters, digits, colons (:), underscores (_), and hyphens (-). It must start with a letter and cannot start with http://, https://, acs:, or aliyun.

hangzhou-daily-update

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The ID of the request.

473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
Imageobject

The image information.

CreationTimestring

The time when the image was created.

2018-01-10T01:01:10Z
Statusstring

The status 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.

testImageFamily
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 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
self
IsSupportCloudinitboolean

Indicates whether the image supports cloud-init.

true
ImageVersionstring

The version of the image.

2
Usagestring

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.
none
IsSelfSharedstring

Indicates whether the image has been shared to other Alibaba Cloud accounts.

true
Descriptionstring

The description of the image.

testDescription
Sizeinteger

The size of the image. Unit: GiB.

80
Platformstring

The platform of the operating system.

Aliyun
ImageNamestring

The name of the image.

testImageName
OSNamestring

The name of the operating system.

Alibaba Cloud Linux 2.1903
ImageIdstring

The ID of the image.

m-bp1g7004ksh0oeuc****
OSTypestring

The type of the operating system. Valid values:

  • windows
  • linux
linux
IsSubscribedboolean

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

false
ProductCodestring

The product code of the Alibaba Cloud Marketplace image.

jxsc00****
Architecturestring

The image architecture. Valid values:

  • i386
  • x86_64
x86_64
DiskDeviceMappingsarray<object>

The mappings between the disks and snapshots under the image.

DiskDeviceMappingobject
Typestring

The type of the image.

custom
ImportOSSBucketstring

The OSS bucket that contains the imported image file.

testEcsImport
SnapshotIdstring

The ID of the snapshot.

s-bp17ot2q7x72ggtw****
ImportOSSObjectstring

The OSS object corresponding to the imported image file.

imageImport
Sizestring

The size of the disk. Unit: GiB.

80
Devicestring

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

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
/dev/xvdb
Formatstring

The format of the image.

qcow2
Tagsarray<object>

An array that consists of Tag data.

Tagobject
TagValuestring

The tag value of the image.

TestValue
TagKeystring

The tag key of the image.

TestKey

Examples

Sample success responses

JSONformat

{
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "Image": {
    "CreationTime": "2018-01-10T01:01:10Z",
    "Status": "Available",
    "ImageFamily": "testImageFamily",
    "Progress": "100",
    "IsCopied": false,
    "IsSupportIoOptimized": true,
    "ImageOwnerAlias": "self",
    "IsSupportCloudinit": true,
    "ImageVersion": "2",
    "Usage": "none",
    "IsSelfShared": "true",
    "Description": "testDescription",
    "Size": 80,
    "Platform": "Aliyun",
    "ImageName": "testImageName",
    "OSName": "Alibaba Cloud Linux 2.1903",
    "ImageId": "m-bp1g7004ksh0oeuc****",
    "OSType": "linux",
    "IsSubscribed": false,
    "ProductCode": "jxsc00****",
    "Architecture": "x86_64",
    "DiskDeviceMappings": {
      "DiskDeviceMapping": [
        {
          "Type": "custom",
          "ImportOSSBucket": "testEcsImport",
          "SnapshotId": "s-bp17ot2q7x72ggtw****",
          "ImportOSSObject": "imageImport",
          "Size": "80",
          "Device": "/dev/xvdb",
          "Format": "qcow2"
        }
      ]
    },
    "Tags": {
      "Tag": [
        {
          "TagValue": "TestValue",
          "TagKey": "TestKey"
        }
      ]
    }
  }
}

Error codes

HTTP status codeError codeError messageDescription
403InvalidUser.UnauthorizedThe user is not authorized.The account you are currently using does not have permission.
404InvalidRegionId.NotFoundThe RegionId provided does not exist.The specified region does not exist.

For a list of error codes, visit the Service error codes.