DescribeSnapshots - - Alibaba Cloud ドキュメントセンター

Usage notes

You can specify multiple request parameters such as InstanceId, DiskId, and SnapshotIds to be queried. Specified parameters have logical AND relations. Only the specified parameters are included in the filter conditions.

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

Parameter	Type	Required	Example	Description
Action	String	Yes	DescribeSnapshots	The operation that you want to perform. Set the value to DescribeSnapshots.
InstanceId	String	No	i-bp67acfmxazb4p****	The ID of the instance.
DiskId	String	No	d-bp67acfmxazb4p****	The ID of the disk.
SnapshotLinkId	String	No	sl-bp1grgphbcc9brb5****	The ID of the snapshot chain.
RegionId	String	Yes	cn-hangzhou	The region ID of the disk. You can call the DescribeRegions operation to query the most recent region list.
SnapshotIds	String	No	["s-bp67acfmxazb4p**", "s-bp67acfmxazb5p", ... "s-bp67acfmxazb6p**"]	The IDs of snapshots. The value can be a JSON array that consists of up to 100 snapshot IDs. Separate the snapshot IDs with commas (,).
PageNumber	Integer	No	1	The page number. Page starts from page 1. Default value: 1.
PageSize	Integer	No	10	The number of entries per page. Maximum value: 100. Default value: 10.
NextToken	String	No	caeba0bbb2be03f84eb48b699f0a4883	The pagination token that is used in this request to retrieve a new page of results. You do not need to specify this parameter for the first request. You must specify the token that is obtained from the previous query as the value of NextToken.
MaxResults	Integer	No	10	The maximum number of entries per page. Maximum value: 100. Default value: 10.
SnapshotName	String	No	testSnapshotName	The name of the snapshot.
Status	String	No	all	The state of the snapshot. Valid values: progressing: The snapshot is being created. accomplished: The snapshot is created. failed: The snapshot fails to be created. all (default): This value indicates all snapshot states.
SnapshotType	String	No	all	The type of the snapshot. Valid values: auto: automatic snapshot user: manual snapshot all (default): all snapshot types
Filter.1.Key	String	No	CreationStartTime	The key of filter 1 that is used to query resources. Set the value to `CreationStartTime`. You can set a time by specifying both `Filter.1.Key` and `Filter.1.Value` to query resources that were created after the time.
Filter.2.Key	String	No	CreationEndTime	The key of filter 2 that is used to query resources. Set the value to `CreationEndTime`. You can specify a time by specifying both `Filter.2.Key` and `Filter.2.Value` to query resources that were created before the time.
Filter.1.Value	String	No	2019-12-13T17:00Z	The value of filter 1 that is used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.1.Key`. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.
Filter.2.Value	String	No	2019-12-13T22:00Z	The value of filter 2 that is used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.2.Key`. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.
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 images or disks.
SourceDiskType	String	No	Data	The source disk type of the snapshot. Valid values: system: system disk data: data disk Note The value of this parameter is case-insensitive.
Encrypted	Boolean	No	false	Specifies whether the snapshot is encrypted. Default value: false.
ResourceGroupId	String	No	rg-bp67acfmxazb4p****	The ID of the resource group to which the snapshot belongs. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group are returned. Note Resources in the default resource group are displayed in the response regardless of how this parameter is set.
DryRun	Boolean	No	false	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs only a dry run. The system checks the AccessKey pair, the permissions of the RAM user, and the required parameters. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned. false (default): performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
KMSKeyId	String	No	0e478b7a-4262-4802-b8cb-00d3fb40****	The ID of the Key Management Service (KMS) key used by the data disk.
Category	String	No	Standard	The category of the snapshot. Valid values: Standard: normal snapshot Flash: local snapshot The local snapshot feature is replaced by the instant access feature. When you specify this parameter, take note of the following items: If you have used local snapshots before December 14, 2020, you can use this parameter. If you have not used local snapshots before December 14, 2020, you cannot use this parameter. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
Tag.N.key	String	No	SnapshotTest	The key of tag N of the snapshot. Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure future compatibility.
Tag.N.Key	String	No	TestKey	The key of tag N of the snapshot. 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 are returned. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added are returned. To query more than 1,000 resources that have the specified tags added, call the ListTagResources operation.
Tag.N.Value	String	No	TestValue	The value 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. Note This parameter will be removed in the future. We recommend that you use Tag.N.Value to ensure future compatibility.

Response parameters

Parameter	Type	Example	Description
NextToken	String	caeba0bbb2be03f84eb48b699f0a4883	A pagination token. It can be used in the next request to retrieve a new page of results.
PageSize	Integer	10	The number of entries per page.
PageNumber	Integer	1	The page number.
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E	The ID of the request.
TotalCount	Integer	1	The total number of snapshots returned.
Snapshots	Array of Snapshot		The details about the snapshots.
Snapshot
Status	String	accomplished	The state of the snapshot. Valid values: progressing accomplished failed
CreationTime	String	2020-08-20T14:52:28Z	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.
Progress	String	100%	The progress of the snapshot creation task. Unit: percent (%).
InstantAccess	Boolean	false	Indicates whether the instant access feature is enabled. Valid values: true: The instant access feature is enabled. This feature can be enabled only for enhanced SSDs (ESSDs). false: The instant access feature is disabled. The snapshot is a normal snapshot for which the instant access feature is disabled.
Available	Boolean	false	Indicates whether the snapshot can be used to create or roll back disks. Valid values: true: The snapshot can be used to create or roll back disks. false: The snapshot cannot be used to create or roll back disks.
RemainTime	Integer	38	The remaining time required to create the snapshot. Unit: seconds.
SourceDiskSize	String	40	The capacity of the source disk. Unit: GiB.
RetentionDays	Integer	30	The retention period of the automatic snapshot.
SourceDiskType	String	system	The type of the source disk. Valid values: system data
SourceStorageType	String	disk	The type of the source disk. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.
Usage	String	image	Indicates whether the snapshot has been used to create images or disks. Valid values: image disk image_disk none
LastModifiedTime	String	2020-08-25T14:18:09Z	The time when the snapshot was last modified. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
Encrypted	Boolean	false	Indicates whether the snapshot is encrypted.
SnapshotType	String	all	The type of the snapshot. Valid values: auto or timer: 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 for which the snapshot was created is released.
SnapshotName	String	testSnapshotName	The name of the snapshot. This parameter is returned only if a snapshot name was specified when the snapshot was created.
InstantAccessRetentionDays	Integer	30	The duration of the instant access feature. The instant access feature is automatically disabled when the specified duration expires. By default, the value of this parameter is the same as that of `RetentionDays`.
Description	String	testDescription	The description of the snapshot.
SnapshotId	String	s-bp67acfmxazb4p****	The ID of the snapshot.
ResourceGroupId	String	rg-bp67acfmxazb4p****	The ID of the resource group.
Category	String	standard	The category of the snapshot. Note This parameter will be removed in the future. We recommend that you use the `InstantAccess` parameter to ensure future compatibility.
KMSKeyId	String	0e478b7a-4262-4802-b8cb-00d3fb40****	The ID of the KMS key used by the data disk.
SnapshotSN	String	64472-116742336-61976****	The serial number of the snapshot.
ProductCode	String	jxsc000****	The product code of the Alibaba Cloud Marketplace image.
SourceSnapshotId	String	s-bp67acfmxazb4p****	The ID of the source snapshot.
SourceRegionId	String	cn-hangzhou	The region ID of the source snapshot.
Tags	Array of Tag		The tags of the snapshot.
Tag
TagValue	String	TestValue	The tag value of the snapshot.
TagKey	String	TestKey	The tag key of the snapshot.

Examples

Sample requests

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

Sample success responses

XML format

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

<DescribeSnapshotsResponse>
    <TotalCount>1</TotalCount>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
    <PageSize>10</PageSize>
    <NextToken>caeba0bbb2be03f84eb48b699f0a4883</NextToken>
    <PageNumber>1</PageNumber>
    <Snapshots>
        <Snapshot>
            <Status>accomplished</Status>
            <InstantAccess>false</InstantAccess>
            <Progress>100%</Progress>
            <Available>false</Available>
            <Usage>image</Usage>
            <Description>testDescription</Description>
            <Category>standard</Category>
            <KMSKeyId>0e478b7a-4262-4802-b8cb-00d3fb40****</KMSKeyId>
            <ProductCode>jxsc000****</ProductCode>
            <Encrypted>false</Encrypted>
            <SnapshotName>testSnapshotName</SnapshotName>
            <SourceDiskId>d-bp67acfmxazb4ph****</SourceDiskId>
            <SourceStorageType>disk</SourceStorageType>
            <SnapshotId>s-bp67acfmxazb4p****</SnapshotId>
            <SnapshotSN>64472-116742336-61976****</SnapshotSN>
            <SourceDiskSize>40</SourceDiskSize>
            <CreationTime>2020-08-20T14:52:28Z</CreationTime>
            <LastModifiedTime>2020-08-25T14:18:09Z</LastModifiedTime>
            <SnapshotType>all</SnapshotType>
            <SourceDiskType>system</SourceDiskType>
            <Tags>
            </Tags>
        </Snapshot>
    </Snapshots>
</DescribeSnapshotsResponse>

JSON format

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

{
  "TotalCount" : 1,
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "PageSize" : 10,
  "NextToken" : "caeba0bbb2be03f84eb48b699f0a4883",
  "PageNumber" : 1,
  "Snapshots" : {
    "Snapshot" : [ {
      "Status" : "accomplished",
      "InstantAccess" : false,
      "Progress" : "100%",
      "Available" : "false",
      "Usage" : "image",
      "Description" : "testDescription",
      "Category" : "standard",
      "KMSKeyId" : "0e478b7a-4262-4802-b8cb-00d3fb40****",
      "ProductCode" : "jxsc000****",
      "Encrypted" : false,
      "SnapshotName" : "testSnapshotName",
      "SourceDiskId" : "d-bp67acfmxazb4ph****",
      "SourceStorageType" : "disk",
      "SnapshotId" : "s-bp67acfmxazb4p****",
      "SnapshotSN" : "64472-116742336-61976****",
      "SourceDiskSize" : 40,
      "CreationTime" : "2020-08-20T14:52:28Z",
      "LastModifiedTime" : "2020-08-25T14:18:09Z",
      "SnapshotType" : "all",
      "SourceDiskType" : "system",
      "Tags" : {
        "Tag" : [ ]
      }
    } ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	The Tag.N.Key and Tag.N.Value values do not correspond to each other.
400	InvalidTagCount	The specified tags are beyond the permitted range.	The maximum number of tags is exceeded.
403	InvalidSnapshotIds.Malformed	The amount of specified specified snapshot Ids exceeds the limit.	Invalid SnapshotIds format.
403	InvalidSnapshotCategory.Malformed	The specified Category is not valid.	Invalid Category value.
404	InvalidFilterKey.NotFound	The specified FilterKey is not found.	The filter key is not found.
404	InvalidFilterValue	The specified FilterValue exceeds the limit.	Invalid filter value.
404	InvalidUsage	The specifed Usage is not valid.	Invalid Usage value.
404	InvalidStatus.NotFound	The specified Status is not found.	Invalid Status value.
404	InvalidSnapshotLinkId.NotFound	The specified snapshot link is not found.	The SnapshotLinkId value is not found.
500	InternalError	The request processing has failed due to some unknown error.	An internal error occurred. Try again later.

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