Queries the list of snapshots for a cloud disk, including information such as the snapshot status, the remaining time for snapshot creation, and the retention period of automatic snapshots.
Operation description
InstanceId, DiskId, and SnapshotIds are not required request parameters, but you can use them to build filter logic. The logical relationship among these parameters is AND.
When you invoke API operations by using Cloud Assistant CLI, request parameter values of different data types must follow specific format requirements. For details, see CLI parameter format description.
Request examples:
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
ecs:DescribeSnapshots |
get |
Snapshot
Snapshot
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| InstanceId |
string |
No |
The instance ID. This parameter specifies the instance whose cloud disk snapshots you want to query. |
i-bp67acfmxazb4p**** |
| DiskId |
string |
No |
The ID of the cloud disk. |
d-bp67acfmxazb4p**** |
| SnapshotLinkId |
string |
No |
The ID of the snapshot chain. |
sl-bp1grgphbcc9brb5**** |
| RegionId |
string |
Yes |
The region ID of the cloud disk. You can call the DescribeRegions operation to query the most recent region list. |
cn-hangzhou |
| SnapshotIds |
string |
No |
The IDs of the snapshots. The value can be a JSON array that consists of up to 100 snapshot IDs. Separate multiple IDs with commas (,). |
["s-bp67acfmxazb4p****", "s-bp67acfmxazb5p****", … "s-bp67acfmxazb6p****"] |
| PageNumber |
integer |
No |
Note
This parameter will be offline soon. We recommend that you use the NextToken and MaxResults parameters to perform paging for paged query operations. |
1 |
| PageSize |
integer |
No |
Note
This parameter will be offline soon. We recommend that you use the NextToken and MaxResults parameters to perform paging for paged query operations. |
10 |
| NextToken |
string |
No |
The pagination token. Obtain the token from the response of the previous request. |
caeba0bbb2be03f84eb48b699f0a4883 |
| MaxResults |
integer |
No |
The number of entries per page during paging for a paged query. Maximum value: 100. Default value: 10. |
10 |
| SnapshotName |
string |
No |
The name of the snapshot. |
testSnapshotName |
| Status |
string |
No |
The status of the snapshot. Valid values:
|
all |
| SnapshotType |
string |
No |
The snapshot creation type. Valid values:
|
all |
| Filter.1.Key |
string |
No |
The filter key used to query resources. The value must be CreationStartTime. If you specify both Filter.1.Key and Filter.1.Value, you can query the resources created after the specified point in time. |
CreationStartTime |
| Filter.2.Key |
string |
No |
The filter key used to query resources. The value must be CreationEndTime. If you specify both Filter.2.Key and Filter.2.Value, you can query the resources created before the specified point in time. |
CreationEndTime |
| Filter.1.Value |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify the Filter.1.Key parameter. The value must be in the yyyy-MM-ddTHH:mmZ format and in UTC+0. |
2019-12-13T17:00Z |
| Filter.2.Value |
string |
No |
The filter value used to query resources. If you specify this parameter, you must also specify the Filter.2.Key parameter. The value must be in the yyyy-MM-ddTHH:mmZ format and in UTC+0. |
2019-12-13T22:00Z |
| Usage |
string |
No |
The usage of the snapshot. Valid values:
|
none |
| SourceDiskType |
string |
No |
The type of the source cloud disk. Valid values:
Note
The value is not case-sensitive. |
system |
| Encrypted |
boolean |
No |
Specifies whether to filter encrypted snapshots. Default value: false. |
false |
| ResourceGroupId |
string |
No |
The ID of the resource group. When you use this parameter to filter resources, the resource count cannot exceed 1,000. Note
Filtering by the default resource group is not supported. |
rg-bp67acfmxazb4p**** |
| DryRun |
boolean |
No |
Specifies whether to perform only a dry run on the request. Valid values:
|
false |
| KMSKeyId |
string |
No |
The ID of the KMS key used for the data disk. |
0e478b7a-4262-4802-b8cb-00d3fb40**** |
| Category |
string |
No |
The snapshot type. Valid values:
|
Standard |
| Tag |
array<object> |
No |
The list of tags. |
|
|
object |
No |
|||
| key |
string |
No |
The tag key of the resource. Note
To improve compatibility, use the Tag.N.Key parameter. |
SnapshotTest |
| Key |
string |
No |
The tag key of the snapshot. Valid values of N: 1 to 20. If you use a single tag to filter resources, the resource count of queried resources cannot exceed 1,000. If you use multiple tags to filter resources, the resource count of queried resources that attach to all the specified tags cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources operation to query the resources. |
TestKey |
| Value |
string |
No |
The tag value of the snapshot. Valid values of N: 1 to 20. |
TestValue |
| value |
string |
No |
The tag value of the resource. Note
To improve compatibility, use the Tag.N.Value parameter. |
SnapshotTest |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| NextToken |
string |
The pagination token for the next query. |
caeba0bbb2be03f84eb48b699f0a4883 |
| PageSize |
integer |
Note
This parameter will soon be deprecated. Use NextToken and MaxResults for paged queries. |
10 |
| PageNumber |
integer |
Note
This parameter will soon be deprecated. Use NextToken and MaxResults for paged queries. |
1 |
| RequestId |
string |
The request ID. |
473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E |
| TotalCount |
integer |
The total number of snapshots. Note
When you use the MaxResults and NextToken parameters for paged queries, the returned value of TotalCount is invalid. |
1 |
| Snapshots |
object |
||
| Snapshot |
array<object> |
The snapshot details. |
|
|
array<object> |
|||
| Status |
string |
The snapshot status. Valid values:
|
accomplished |
| CreationTime |
string |
The creation time. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. |
2020-08-20T14:52:28Z |
| Progress |
string |
The snapshot creation progress, in percentage. |
100% |
| InstantAccess |
boolean |
Indicates whether the snapshot instant access feature is enabled. Valid values:
Note
[Deprecated] This parameter is deprecated. Standard snapshots of enterprise SSDs are upgraded to instant access by default. No additional configuration or fees are required. |
false |
| Available |
boolean |
Indicates whether the snapshot can be used to create disks, roll back disks, or share snapshots. Valid values:
|
false |
| RemainTime |
integer |
The remaining time required to create the snapshot. Unit: seconds. |
38 |
| SourceDiskSize |
string |
The capacity of the source disk. Unit: GiB. |
40 |
| RetentionDays |
integer |
The retention period of the automatic snapshot, in days. |
30 |
| SourceDiskType |
string |
The type of the source disk. Valid values:
|
system |
| SourceStorageType |
string |
The storage type of the source disk. Note
This parameter will soon be deprecated. To improve compatibility, use other parameters instead. |
disk |
| Usage |
string |
The usage of the snapshot. Valid values:
|
image |
| LastModifiedTime |
string |
The last modification time of the snapshot. The time is displayed in UTC and follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. |
2020-08-25T14:18:09Z |
| Encrypted |
boolean |
Indicates whether the snapshot is encrypted. Valid values:
|
false |
| SnapshotType |
string |
The automatic creation type. Valid values:
|
all |
| SourceDiskId |
string |
The ID of the source disk. If the source disk of the snapshot has been released, this field is still retained. |
d-bp67acfmxazb4ph**** |
| SnapshotName |
string |
The display name of the snapshot. This parameter is returned only if a display name was specified when the snapshot was created. |
testSnapshotName |
| InstantAccessRetentionDays |
integer |
The retention period of the snapshot instant access feature. After the retention period expires, the snapshot instant access feature is automatically disabled. Default value: the value of the RetentionDays parameter. Note
[Deprecated] This parameter is deprecated. Standard snapshots of enterprise SSDs are upgraded to instant access by default. No additional configuration or fees are required. |
30 |
| Description |
string |
The description. |
testDescription |
| SnapshotId |
string |
The snapshot ID. |
s-bp67acfmxazb4p**** |
| RegionId |
string |
The region ID of the snapshot. |
cn-hangzhou |
| ResourceGroupId |
string |
The resource group ID. |
rg-bp67acfmxazb4p**** |
| Category |
string |
The snapshot type. Valid values:
|
standard |
| KMSKeyId |
string |
The ID of the KMS key used for the data disk. |
0e478b7a-4262-4802-b8cb-00d3fb40**** |
| SnapshotSN |
string |
The snapshot serial number. |
64472-116742336-61976**** |
| ProductCode |
string |
The product code inherited from the Alibaba Cloud Marketplace image. |
jxsc000**** |
| SourceSnapshotId |
string |
The source snapshot. |
s-bp67acfmxazb4p**** |
| SourceRegionId |
string |
The region of the source snapshot. |
cn-hangzhou |
| FullSnapshotSizeInBytes |
integer |
The full size of the snapshot. Unit: bytes. |
65535 |
| Tags |
object |
||
| Tag |
array<object> |
The tags. |
|
|
object |
|||
| TagValue |
string |
The tag value of the snapshot. |
TestValue |
| TagKey |
string |
The tag key of the snapshot. |
TestKey |
| SnapshotLinkId |
string |
The ID of the snapshot chain associated with the snapshot. |
sl-bp1grgphbcc9brb5**** |
Examples
Success response
JSON format
{
"NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
"PageSize": 10,
"PageNumber": 1,
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
"TotalCount": 1,
"Snapshots": {
"Snapshot": [
{
"Status": "accomplished",
"CreationTime": "2020-08-20T14:52:28Z",
"Progress": "100%",
"InstantAccess": false,
"Available": false,
"RemainTime": 38,
"SourceDiskSize": "40",
"RetentionDays": 30,
"SourceDiskType": "system",
"SourceStorageType": "disk",
"Usage": "image",
"LastModifiedTime": "2020-08-25T14:18:09Z",
"Encrypted": false,
"SnapshotType": "all",
"SourceDiskId": "d-bp67acfmxazb4ph****",
"SnapshotName": "testSnapshotName",
"InstantAccessRetentionDays": 30,
"Description": "testDescription",
"SnapshotId": "s-bp67acfmxazb4p****",
"RegionId": "cn-hangzhou",
"ResourceGroupId": "rg-bp67acfmxazb4p****",
"Category": "standard",
"KMSKeyId": "0e478b7a-4262-4802-b8cb-00d3fb40****",
"SnapshotSN": "64472-116742336-61976****",
"ProductCode": "jxsc000****",
"SourceSnapshotId": "s-bp67acfmxazb4p****",
"SourceRegionId": "cn-hangzhou",
"FullSnapshotSizeInBytes": 65535,
"Tags": {
"Tag": [
{
"TagValue": "TestValue",
"TagKey": "TestKey"
}
]
},
"SnapshotLinkId": "sl-bp1grgphbcc9brb5****"
}
]
}
}
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 specified Tag.N.Key and Tag.N.Value parameters do not correspond to each other. |
| 400 | InvalidTagCount | The specified tags are beyond the permitted range. | The number of specified tags exceeds the upper limit. |
| 500 | InternalError | The request processing has failed due to some unknown error. | |
| 403 | InvalidSnapshotIds.Malformed | The amount of specified specified snapshot Ids exceeds the limit. | |
| 403 | InvalidSnapshotCategory.Malformed | The specified Category is not valid. | The specified Category parameter is invalid. |
| 403 | InvalidCategory.SnapshotLinkMismatch | The specified category does not match the actual category of the snapshot link. | The specified category does not match the snapshot chain. |
| 404 | InvalidFilterKey.NotFound | The specified FilterKey is not found. | The specified filter key does not exist. |
| 404 | InvalidFilterValue | The specified FilterValue exceeds the limit. | The specified filter value is invalid. |
| 404 | InvalidUsage | The specifed Usage is not valid. | The specified Usage parameter is invalid. |
| 404 | InvalidSourceDiskType | The specifed SourceDiskType is not valid. | |
| 404 | InvalidStatus.NotFound | The specified Status is not found. | |
| 404 | InvalidSnapshotType.NotFound | The specfied SnapshotType is not found. | |
| 404 | InvalidSnapshotLinkId.NotFound | The specified snapshot link is not found. | The specified snapshot chain does not exist. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.