You can call this operation to query all snapshots of an ECS instance or a disk.

Description

You can specify multiple request parameters such as InstanceId, DiskId, and SnapshotIds. Specified parameters have logical AND relations.

When calling an API operation through Alibaba Cloud CLI, specify request parameter values of different data types in required formats. For more information, see CLI parameter formats.

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
RegionId String Yes cn-hangzhou

The region ID of the instance or disk to be queried. You can call the DescribeRegions operation to query the most recent region list.

Action String No DescribeSnapshots

The operation that you want to perform. Set the value to DescribeSnapshots.
DiskId String No d-diskid1

The ID of the disk.
DryRun Boolean No false

Specifies whether to check the request only. Default value: false. Valid values:

  • true: The request is checked but snapshots of the instance or disk are not queried. Check items include whether your AccessKey pair is valid, whether RAM users are authorized, and whether the required parameters are specified. If the check fails, the corresponding error message is returned. If the check succeeds, the DryRunOperation error code is returned.
  • false: The request is checked, and a 2XX HTTP status code is returned and snapshots of the instance or disk are queried if the check succeeds.
Encrypted Boolean No false

Specifies whether to filter encrypted snapshots. Default value: false.

Filter.1.Key String No CreationStartTime

A filter key used to query resources. Valid value: CreationStartTime.
Filter.1.Value String No 2017-12-05T22:40:00Z

A filter value used to query resources. The parameter value must be the start time when the resource is created (CreationStartTime).

Filter.2.Key String No CreationEndTime

A filter key used to query resources. Valid value: CreationEndTime
Filter.2.Value String No 2017-12-06T22:40:00Z

A filter value used to query resources. The parameter value must be the end time when the resource is created (CreationEndTime).

InstanceId String No i-instanceid1

The ID of the instance to be queried.
KMSKeyId String No 0e478b7a-4262-4802-b8cb-00d3fb4082**

The KMS key ID corresponding to the data disk.
PageNumber Integer No 1

The number of the page to return. Pages start from page 1.

Default value: 1.

PageSize Integer No 10

The number of entries to return on each page. Valid values: 1 to 100

Default value: 10.

ResourceGroupId String No rg-resourcegrouid

The ID of the resource group.
SnapshotIds String No ["s-xxxxxxxxx", "s-yyyyyyyyy", … "s-zzzzzzzzz"]

The IDs of the snapshots. It can be a JSON array that consists of snapshot IDs. Separate multiple snapshot IDs with commas (,). A maximum of 100 snapshot IDs can be entered at a time.

SnapshotLinkId String No d-25okbh2**

The ID of the snapshot chain.
SnapshotName String No FinanceJoshua

The name of the snapshot.
SnapshotType String No all

The type of the snapshot. Default value: all. Valid values:

  • auto: automatic snapshot
  • user: manual snapshot
  • all: all snapshot types
SourceDiskType String No Data

The type of the source disk from which the snapshot is created. Valid values:

  • system: system disk
  • data: data disk
Status String No all

The status of the snapshot. Default value: all. Valid values:

  • progressing: The snapshot is being created.
  • accomplished: The snapshot is created.
  • failed: The snapshot failed to be created.
  • all: all snapshot statuses
Tag.N.Key String No FinanceDept

The key of the Nth tag of the snapshot. Valid values of N: 1 to 20.
Tag.N.Value String No FinanceDeptJoshua

The value of the Nth tag of the snapshot. Valid values of N: 1 to 20.
Usage String No none

Specifies whether the snapshot is used to create images or disks. Valid values:

  • image: The snapshot is used to create custom images.
  • disk: The snapshot is used to create disks.
  • image_disk: The snapshot is used to create custom images and data disks.
  • none: The snapshot is not used to create custom images or disks.

Response parameters

Parameter Type Example Description 
PageNumber Integer 1

The page number of the returned page.
PageSize Integer 10

The number of entries returned per page.
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.
Snapshots Array

The details of snapshots.
Snapshot

The details of the snapshot.
CreationTime String 2014-07-24T13:00:52Z

The creation time of the snapshot. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

Description String FinanceDept

The description of the snapshot.
Encrypted Boolean false

Indicates whether the snapshot is encrypted.
KMSKeyId String 0e478b7a-4262-4802-b8cb-00d3fb40826X

The KMS key ID corresponding to the data disk.
ProductCode String jxsc000***

The product code in the Alibaba Cloud Marketplace image.
Progress String 100

The progress of a snapshot being created. Unit: percent (%).
RemainTime Integer 38

The time remaining for a snapshot creation task before it is completed. Unit: seconds.
ResourceGroupId String rg-resourcegrouid

The ID of the resource group.
RetentionDays Integer 30

The number of days that an automatic snapshot is retained.
SnapshotId String s-snapshotid1

The ID of the snapshot.
SnapshotName String FinanceJoshua

The name of the snapshot. This parameter is returned only if a snapshot name was specified during creation.

SnapshotSN String 64472-116742336-619762***

The serial number of the snapshot.
SourceDiskId String d-diskid1

The ID of the source disk. This parameter is retained even after the source disk of the snapshot is deleted.

SourceDiskSize String 2000

The size of the source disk. Unit: GiB.
SourceDiskType String Data

The type of the source disk. Valid values:

  • System
  • Data
SourceStorageType String disk

The category of the source disk.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
Status String accomplished

The status of the snapshot. Valid values:

  • progressing
  • accomplished
  • failed
Tags Array

The tags of the snapshot.
Tag

The tag of the snapshot.
TagKey String FinanceDept

The tag key of the snapshot.
TagValue String FinanceDeptJoshua

The tag value of the snapshot.
Usage String none

Indicates whether the snapshot was used to create images or disks. Valid values:

  • image
  • disk
  • image_disk
  • none
TotalCount Integer 36

The total number of snapshots.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeSnapshots
&RegionId=cn-hangzhou
&InstanceId=i-instanceid1
&DiskId=d-diskid1
&SnapshotIds=["s-xxxxxxxxx", "s-yyyyyyyyy", … "s-zzzzzzzzz"]
&PageNumber=1
&PageSize=10
&SnapshotName=FinanceJoshua
&Status=all
&SnapshotType=all
&Usage=none
&SourceDiskType=Data
&Tag.1.Key=FinanceDept
&Tag.1.Value=FinanceDeptJoshua
&Encrypted=false
&DryRun=false
&<Common request parameters>

Sample success responses

XML format 

<DescribeSnapshotsResponse>
      <Snapshots>
            <Snapshot>
                  <CreationTime>2014-07-24T13:00:52Z</CreationTime>
                  <Description></Description>
                  <SourceDiskId>d-23x0r79**</SourceDiskId>
                  <SourceDiskType>DATA</SourceDiskType>
                  <ProductCode></ProductCode>
                  <SnapshotName>auto_20140724_2</SnapshotName>
                  <Progress>100%</Progress>
                  <SourceDiskSize>50</SourceDiskSize>
                  <Status>accomplished</Status>
                  <SnapshotId>s-23f2i9s**</SnapshotId>
                  <Usage>none</Usage>
            </Snapshot>
            <Snapshot>
                  <CreationTime>2014-07-24T13:00:42Z</CreationTime>
                  <Description></Description>
                  <SourceDiskId>d-94j355j**</SourceDiskId>
                  <SourceDiskType>DATA</SourceDiskType>
                  <ProductCode></ProductCode>
                  <SnapshotName>auto_20140724_2</SnapshotName>
                  <Progress>100%</Progress>
                  <SourceDiskSize>5</SourceDiskSize>
                  <Status>accomplished</Status>
                  <SnapshotId>s-23izto5**</SnapshotId>
                  <Usage>none</Usage>
            </Snapshot>
      </Snapshots>
      <PageNumber>1</PageNumber>
      <PageSize>2</PageSize>
      <TotalCount>36</TotalCount>
      <RequestId>2F409D67-329A-4405-B924-2FC28566B366</RequestId>
</DescribeSnapshotsResponse>

JSON format 

{
	"PageNumber":1,
	"TotalCount":36,
	"PageSize":2,
	"RequestId":"659F91C6-1949-43B0-90C4-B6342CA757D5",
	"Snapshots":{
		"Snapshot":[
			{
				"CreationTime":"2015-07-30T05:00:14Z",
				"Status":"accomplished",
				"SnapshotName":"auto_20150730_3",
				"SourceDiskType":"system",
				"SourceDiskId":"d-944qyqj**",
				"SnapshotId":"s-943ypfg**",
				"SourceDiskSize":20,
				"Progress":"100%",
				"Usage":"none"
			},
			{
				"CreationTime":"2015-07-30T05:00:14Z",
				"Status":"accomplished",
				"SnapshotName":"auto_20150730_3",
				"SourceDiskType":"system",
				"SourceDiskId":"d-94j355j**",
				"SnapshotId":"s-94osg32**",
				"SourceDiskSize":20,
				"Progress":"100%",
				"Usage":"none"
			}
		]
	}
}

Error codes

HTTP status code Error code Error message Description
403 InvalidSnapshotIds.Malformed The amount of specified specified snapshot Ids exceeds the limit. The error message returned because the specified value of the SnapshotIds parameter is invalid.
404 InvalidFilterKey.NotFound The error message returned because the specified start time or end time is invalid.
404 InvalidFilterValue The error message returned because the format of the specified time is invalid.
404 InvalidUsage The specifed Usage is not valid The error message returned because the specified value of the Usage parameter (image, disk, image_disk, or none) is invalid.
404 InvalidSourceDiskType The specifed SourceDiskType is not valid The error message returned because the specified value of the SourceDiskType parameter is invalid.
404 InvalidStatus.NotFound The specified Status is not found The error message returned because the specified Status parameter does not exist.
404 InvalidSnapshotType.NotFound The specfied SnapshotType is not found The error message returned because the specified snapshot type does not exist.
400 InvalidTag.Mismatch The 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.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the number of specified tags exceeds the upper limit.
500 InternalError The request processing has failed due to some unknown error. The error message returned because an internal error has occurred. Try again later. If the problem persists, submit a ticket.
404 InvalidSnapshotLinkId.NotFound The specified snapshot link is not found. The error message returned because the specified snapshot chain does not exist.

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