tencent cloud

Feedback

DescribeSnapshots

Last updated: 2023-08-18 15:47:44

1. API Description

Domain name for API request: ecm.tencentcloudapi.com.

This API is used to query the list of snapshots.

  • You can filter results by snapshot ID and the ID and type of the cloud disk for which the snapshot is created. The relationship between different filters is AND. For more information on filters, see Filter.
  • If no parameter is defined, the status of a certain number of snapshots under the current account will be returned. The number is specified by Limit and is 20 by default.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: DescribeSnapshots.
Version Yes String Common Params. The value used for this API: 2019-07-19.
Region No String Common Params. This parameter is not required for this API.
SnapshotIds.N No Array of String List of IDs of the snapshots to be queried. SnapshotIds and Filters cannot be specified at the same time.
Filters.N No Array of Filter Filter. SnapshotIds and Filters cannot be specified at the same time.
  • snapshot-id - Array of String - Required: no - (Filter) Filter by snapshot ID, such as snap-11112222.
  • snapshot-name - Array of String - Required: no - (Filter) Filter by snapshot name.
  • snapshot-state - Array of String - Required: no - (Filter) Filter by snapshot status. NORMAL: normal; CREATING: creating; ROLLBACKING: rolling back.
  • disk-usage - Array of String - Required: no - (Filter) Filter by the type of the cloud disk from which a snapshot is created. SYSTEM_DISK: system disk; DATA_DISK: data disk.
  • project-id - Array of String - Required: no - (Filter) Filter by the project ID of the cloud disk.
  • disk-id - Array of String - Required: no - (Filter) Filter by the ID of the cloud disk from which a snapshot is created.
  • zone - Array of String - Required: no - (Filter) Filter by AZ.
  • encrypt - Array of String - Required: no - (Filter) Filter by whether a snapshot is created from an encrypted cloud disk. TRUE: yes; FALSE: no.
  • snapshot-type- Array of String - Required: no - (Filter) Filter by the snapshot type specified in snapshot-type.
    (SHARED_SNAPSHOT: shared snapshot | PRIVATE_SNAPSHOT: private snapshot.)
  • Limit No Integer Number of returned results. Default value: 20. Maximum value: 100. For more information on Limit, see the relevant section of the API Overview.
    OrderField No String Field by which snapshots are sorted. Valid values:
  • CREATE_TIME: sort by snapshot creation time
    Snapshots are sorted by creation time by default.
  • Offset No Integer Offset. Default value: 0. For more information on Offset, see the relevant section of the API Overview.
    Order No String Sorting order of cloud disks. Valid values:
  • ASC: ascending
  • DESC: descending.
  • 3. Output Parameters

    Parameter Name Type Description
    TotalCount Integer Number of snapshots.
    SnapshotSet Array of Snapshot List of snapshot details.
    RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

    4. Example

    Example1 Querying snapshots in NORMAL status in Guangzhou Zone 2

    Input Example

    https://ecm.tencentcloudapi.com/?Action=DescribeSnapshots
    &Filters.0.Name=snapshot-state
    &Filters.0.Values.0=NORMAL
    &Filters.1.Name=zone
    &Filters.1.Values.0=ap-guangzhou-2
    &<Common request parameters>
    

    Output Example

    {
        "Response": {
            "TotalCount": 2,
            "RequestId": "4ab150b9-538d-48fb-8821-7fa185f1d07c",
            "SnapshotSet": [
                {
                    "Placement": {
                        "ProjectId": 0,
                        "Zone": "ap-guangzhou-2"
                    },
                    "TimeStartShare": "2020-09-22",
                    "CopyFromRemote": false,
                    "IsPermanent": false,
                    "DiskUsage": "DATA_DISK",
                    "DeadlineTime": "2019-07-15 00:00:00",
                    "Percent": 100,
                    "SnapshotId": "snap-lfo7xxxx",
                    "ShareReference": 0,
                    "SnapshotType": "PRIVATE_SNAPSHOT",
                    "DiskSize": 10,
                    "DiskId": "disk-aq3k1jn0",
                    "SnapshotName": "auto_disk-aq3k1jn0_20190708_00",
                    "Images": [],
                    "CopyingToRegions": [],
                    "Encrypt": false,
                    "CreateTime": "2019-07-08 00:03:13",
                    "ImageCount": 0,
                    "SnapshotState": "NORMAL"
                },
                {
                    "Placement": {
                        "ProjectId": 0,
                        "Zone": "ap-guangzhou-2"
                    },
                    "TimeStartShare": "2020-09-22",
                    "CopyFromRemote": false,
                    "IsPermanent": false,
                    "DiskUsage": "DATA_DISK",
                    "DeadlineTime": "2019-07-15 00:00:00",
                    "Percent": 100,
                    "SnapshotId": "snap-jt5nxxxx",
                    "ShareReference": 0,
                    "SnapshotType": "PRIVATE_SNAPSHOT",
                    "DiskSize": 10,
                    "DiskId": "disk-38hlz2p0",
                    "SnapshotName": "auto_disk-38hlz2p0_20190708_00",
                    "Images": [],
                    "CopyingToRegions": [],
                    "Encrypt": false,
                    "CreateTime": "2019-07-08 00:03:10",
                    "ImageCount": 0,
                    "SnapshotState": "NORMAL"
                }
            ]
        }
    }
    

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation.OperationNotAllow The current operation is not allowed.
    InvalidParameterValue The parameter value is incorrect.
    InvalidParameterValue.InvalidFilter The filter is invalid.
    MissingParameter The parameter is missing.