文档首页/云桌面 Workspace/API参考/云桌面API/快照/查询快照列表 - ListDesktopSnapshot
更新时间：2026-03-17 GMT+08:00
查看PDF
分享

查询快照列表 - ListDesktopSnapshot

功能介绍

查询快照列表。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，当前API调用无需身份策略权限。

URI

GET /v2/{project_id}/snapshots

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID。

表2 Query参数

参数

是否必选

参数类型

描述

desktop_id

否

String

桌面id。

desktop_ids

否

Array of strings

桌面id列表

desktop_name

否

String

桌面名称。

desktop_names

否

Array of strings

桌面名称列表

snapshot_name

否

String

快照名称。

snapshot_names

否

Array of strings

快照名称列表

disk_type

否

String

快照类型。

  • SYSTEM_DISK 系统盘。

  • DATA_DISKS 数据盘。

  • ALL 系统盘和数据盘。

create_type

否

String

快照创建类型。

  • AUTO 定时任务自动创建。

  • MANUALLY 手动创建。

status

否

String

快照状态。

  • creating：表示创建中。

  • restoring：表示恢复中。

  • create_success：表示创建成功。

  • create_failed：表示创建快照失败。

  • restore_success：表示快照恢复成功。

  • restore_failed：表示快照恢复失败。

sort_field

否

String

排序字段名称，需要结合sort_type字段一起使用。

  • create_time 创建时间。

  • snapshot_name 快照名称。

sort_type

否

String

排序类型，默认升序，需要结合sort_field字段一起使用。

  • ASC 升序。

  • DESC 降序。

offset

否

Integer

用于分页查询，查询的起始记录序号，从0开始。

limit

否

Integer

用于分页查询。默认1000,取值范围1-1000。

请求参数

无

响应参数

状态码：200

表3 响应Body参数

参数

参数类型

描述

desktop_snapshots

Array of DesktopSnapshotDetailInfo objects

桌面快照详情列表。

total_count

Integer

桌面快照总数。

表4 DesktopSnapshotDetailInfo

参数

参数类型

描述

snapshot_id

String

桌面快照ID。

snapshot_name

String

桌面快照记录名称。

desktop_id

String

桌面快照对应的桌面id。

desktop_name

String

桌面快照对应的桌面名称。

desktop_sid

String

桌面快照对应的桌面sid。

desktop_pool_id

String

桌面快照对应的桌面池id。

is_system_disk

Boolean

快照对应磁盘类型，true表示系统盘，false表示数据盘。

status

String

快照状态。

  • creating：表示创建中。

  • restoring：表示恢复中。

  • create_success：表示创建成功。

  • create_failed：表示创建快照失败。

  • restore_success：表示快照恢复成功。

  • restore_failed：表示快照恢复失败。

process

Integer

快照任务进度， 取值范围0-100以及null，null表示该快照无任务，0-100表明该任务进度的百分比。

description

String

快照描述。

create_time

String

快照的创建时间，UTC时间，格式为：yyyy-MM-dd'T'HH:mm:ss'Z。'

create_type

String

快照创建类型。

  • AUTO 定时任务自动创建。

  • MANUALLY 手动创建。

last_restore_time

String

快照的最近恢复时间，UTC时间，格式为：yyyy-MM-dd'T'HH:mm:ss'Z。'

restore_fail_reason

String

快照恢复失败原因。

状态码：400

表5 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

error_detail

String

错误详情。

encoded_authorization_message

String

加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。

状态码：403

表6 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

error_detail

String

错误详情。

encoded_authorization_message

String

加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。

状态码：404

表7 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

error_detail

String

错误详情。

encoded_authorization_message

String

加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。

状态码：500

表8 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

error_detail

String

错误详情。

encoded_authorization_message

String

加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。

状态码：default

表9 响应Body参数

参数

参数类型

描述

error_code

String

错误码，失败时返回。

error_msg

String

错误描述。

error_detail

String

错误详情。

encoded_authorization_message

String

加密后的详细拒绝原因，用户可以自行调用STS服务的decode-authorization-message接口进行解密。

请求示例

/v2/bcae3e673fd04716a3b9dacdf58ca336/snapshots

响应示例

状态码：200

OK。

{
  "total_count" : 2,
  "desktop_snapshots" : [ {
    "snapshot_id" : "eed156d9-02a5-46f5-8eb1-54f09ab9fbae",
    "snapshot_name" : "sys0420_xzx03_1713602176593",
    "desktop_id" : "7163a7ba-fc09-4238-ab73-0689ea7f54c3",
    "desktop_name" : "xzx03",
    "desktop_sid" : "22ad6780-3236-4838-b509-8068d254e9de",
    "is_system_disk" : true,
    "status" : "create_success",
    "description" : "description。",
    "create_time" : "2024-04-20T08:36:16Z",
    "create_type" : "MANUALLY"
  }, {
    "snapshot_id" : "a7e996da-20db-4de8-8aff-4c8e4c6d5ed3",
    "snapshot_name" : "AUTOCREATED_AA_1713595811910",
    "desktop_id" : "a3e8d0d0-79df-413d-a327-d702a4fb2e15",
    "desktop_name" : "AA",
    "desktop_sid" : "1346b13d-d3e4-4965-bfb4-5bb880bf7dbf",
    "is_system_disk" : false,
    "status" : "create_success",
    "description" : "description。",
    "create_time" : "2024-04-20T06:50:11Z",
    "create_type" : "AUTO"
  } ]
}

状态码

状态码

描述

200

OK。

400

由于包含语法错误，当前请求无法被服务器理解。

403

没有操作权限。

404

找不到资源。

500

服务内部错误，具体返回错误码请参见错误码说明。

default

默认失败响应。

错误码

请参见错误码。

父主题：快照