DescribeSnapshots - API Reference| Alibaba Cloud Documentation Center

DescribeSnapshots

Edit in GitHub

Last Updated: May 13, 2020 Edit in GitHub

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 to filter responses. These parameters are optional and have a logical relation of AND.

When you call an API operation by using Alibaba Cloud CLI, 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


Parameter	Type	Required	Example	Description
Action	String	No	DescribeSnapshots	The operation that you want to perform. Set the value to DescribeSnapshots.
RegionId	String	Yes	cn-hangzhou	The region ID of the disk. You can call the DescribeRegions operation to query the most recent region list.
InstanceId	String	No	i-bp67acfmxazb4ph***	The ID of the instance to be queried.
DiskId	String	No	d-bp67acfmxazb4ph***	The ID of the disk to be queried.
SnapshotLinkId	String	No	sp-bp67acfmxazb4ph***	The ID of the snapshot chain.
SnapshotIds	String	No	["s-bp67acfmxazb4ph*", "s-bp67acfmxazb4pk", ... "s-bp67acfmxazb4pj**"]	The IDs of the snapshots. This parameter can be a JSON array that consists of multiple snapshot IDs. Separate snapshot IDs with commas (,). A maximum of 100 snapshot IDs can be specified at a time.
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. Maximum value: 100. Default value: 10.
SnapshotName	String	No	SnapshotTest	The name of the snapshot.
Status	String	No	all	The status of the snapshot. Default value: all. Valid values: progressing: The snapshot is being created. accomplished: The snapshot has been created. failed: The snapshot failed to be created. all: all snapshot status.
SnapshotType	String	No	all	The type of the snapshot. Default value: all. Valid values: auto: automatic snapshot user: manual snapshot all: all snapshot types
Filter.1.Key	String	No	CreationStartTime	The key of filter 1 used to query resources. The value must be set to CreationStartTime.
Filter.2.Key	String	No	CreationEndTime	The key of filter 2 used to query resources. The value must be set to CreationEndTime.
Filter.1.Value	String	No	2019-12-13T17:00Z	The value of filter 1 used to query resources. The parameter value must be the start time of the resource creation.
Filter.2.Value	String	No	2019-12-13T22:00Z	The value of filter 2 used to query resources. The parameter value must be the end time of the resource creation.
Usage	String	No	none	Specifies whether the snapshot has been used to create images or disks. Valid values: image: The snapshot has been used to create custom images. disk: The snapshot has been used to create disks. image_disk: The snapshot has been used to create custom images and data disks. none: The snapshot has not been used to create custom images or disks.
SourceDiskType	String	No	Data	The category of the source disk from which the snapshot is created. Valid values: System: system disk Data: data disk
Tag.N.Key	String	No	SnapshotTest	The key of tag N of the snapshot. Valid values of N: 1 to 20.
Tag.N.Value	String	No	SnapshotTest	The value of tag N of the snapshot. Valid values of N: 1 to 20.
Encrypted	Boolean	No	false	Specifies whether to filter encrypted snapshots. Default value: false.
ResourceGroupId	String	No	rg-bp67acfmxazb4ph***	The ID of the resource group.
DryRun	Boolean	No	false	Specifies whether to check the request only. Default value: false. true: The request is checked but available images are not queried. Check items include whether your AccessKey pair is valid, whether RAM users are authorized, and whether the required parameters are set. 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.
KMSKeyId	String	No	0e478b7a-4262-4802-b8cb-00d3fb4082**	The ID of the KMS key corresponding to the data disk.

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		An array of Snapshot data.
Snapshot
Category	String	standard	The type of the snapshot. Valid values: standard: normal snapshot flash: local snapshot
CreationTime	String	2019-12-24T13:00:52Z	The time when the snapshot was created. 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 ID of the KMS key corresponding to the data disk.
LastModifiedTime	String	hide
ProductCode	String	jxsc000***	The product code of the Alibaba Cloud Marketplace image.
Progress	String	100	The progress of a snapshot creation task. Unit: percent (%).
RemainTime	Integer	38	The time remaining for a snapshot creation task. Unit: seconds.
ResourceGroupId	String	rg-bp67acfmxazb4ph***	The ID of the resource group.
RetentionDays	Integer	30	The number of days that an automatic snapshot can be retained.
SnapshotId	String	s-bp67acfmxazb4ph***	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.
SnapshotType	String	all	The type of the snapshot. Default value: all. Valid values: auto: automatic snapshot user: manual snapshot all: all snapshot types
SourceDiskId	String	d-bp67acfmxazb4ph***	The ID of the source disk. This parameter is retained even after the source disk of the snapshot is released.
SourceDiskSize	String	2000	The size of the source disk. Unit: GiB.
SourceDiskType	String	Data	The category of the source disk. Valid values: System: system disk Data: data disk
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: The snapshot was being created. accomplished: The snapshot had been created. failed: The snapshot failed to create.
Tags	Array		An array of Tag data.
Tag
TagKey	String	SnapshotTest	The tag key of the snapshot.
TagValue	String	SnapshotTest	The tag value of the snapshot.
Usage	String	none	Indicates whether the snapshot had been used to create images or disks. Valid values: image: The snapshot had been used to create custom images. disk: The snapshot had been used to create disks. image_disk: The snapshot had been used to create custom images and data disks. none: The snapshot had not been used to create custom images or disks.
TotalCount	Integer	36	The total number of snapshots.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeSnapshots
&RegionId=cn-hangzhou
&InstanceId=i-bp67acfmxazb4ph***
&DiskId=d-bp67acfmxazb4ph***
&SnapshotIds=["s-bp67acfmxazb4ph***", "s-bp67acfmxazb4pk***", ... "s-bp67acfmxazb4pj***"]
&PageNumber=1
&PageSize=10
&SnapshotName=SnapshotTest
&Status=all
&SnapshotType=all
&Usage=none
&SourceDiskType=Data
&Tag.1.Key=SnapshotTest
&Tag.1.Value=SnapshotTest
&Encrypted=false
&DryRun=false
&<Common request parameters>

Sample success responses

XML format

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

JSON format

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

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 SnapshotIds parameter is invalid.
404	InvalidFilterKey.NotFound		The error message returned because the specified start time or end time is invalid.
404	InvalidUsage	The specifed Usage is not valid	The error message returned because the specified Usage parameter value (image, disk, image_disk, or none) is invalid.
404	InvalidSourceDiskType	The specifed SourceDiskType is not valid	The error message returned because the specified SourceDiskType parameter is invalid.
404	InvalidStatus.NotFound	The specified Status is not found	The error message returned because the specified resource status does not exist.
404	InvalidSnapshotType.NotFound	The specified 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 value of the Tag.N.Key parameter does not correspond to that of the Tag.N.Value parameter.
400	InvalidTagCount	The specified tags are beyond the permitted range.	The error message returned because the maximum number of specified tags has been reached.
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.