列出云端备份

查询当前客户端登录账号及所选存储提供方的备份。此接口不会读取本地环境目录的实时大小，也不会恢复环境。

请求

GET /api/listCloudBackups
api-key: REPLACE_WITH_LOCAL_API_KEY

需保持客户端运行，登录有效 VIP（专业版）会员，并具备 local_api 和云同步权限。从客户端 API 页面复制实际本地服务地址和 api-key；API 端口动态分配，不是浏览器 CDP 端口。参见概述与鉴权。

Query 参数

参数	类型	必填	说明
provider	string	否	仅接受 oss 或 webdav；默认使用客户端全局云同步提供方。
page	integer	否	从 1 开始的正整数，默认 1；须在 JavaScript 安全整数范围内。
pageSize	integer	否	1～1000，默认 50。

只接受以上三个 Query 参数，未知参数返回 HTTP 400。分页值必须是无前导零的十进制正整数字符串；空值、0、负数、小数或超出范围的值都会被拒绝，不会自动修正。两个分页参数各自采用默认值，无需成对传入。

有效备份去重后，先按 cloudId 区分大小写的 ASCII 升序排序，再分页。不支持用户指定排序参数。

使用 webdav 前，须先在客户端保存服务器、账号和基础目录配置。接口仅使用这些已保存的设置；不能通过参数传入 WebDAV 地址、用户名、认证密码或 webdav 对象。

cURL

运行前将两处占位符替换为客户端 API 页面的实际值。以下使用 Bash 语法，不含可用凭据。

BASE_URL='http://127.0.0.1:REPLACE_WITH_API_PORT'
API_KEY='REPLACE_WITH_LOCAL_API_KEY'
curl --get "${BASE_URL}/api/listCloudBackups" \
  --header "api-key: ${API_KEY}" \
  --data-urlencode 'provider=oss' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=50'

Python

import requests

base_url = "http://127.0.0.1:REPLACE_WITH_API_PORT"
response = requests.get(
    f"{base_url}/api/listCloudBackups",
    headers={"api-key": "REPLACE_WITH_LOCAL_API_KEY"},
    params={"provider": "oss", "page": 1, "pageSize": 50},
    timeout=60,
)
response.raise_for_status()
print(response.json())

成功响应

HTTP 200；以下 ID 和名称均为虚构示例。

{
  "success": true,
  "data": [
    {
      "cloudId": "8f2b6a91-3d74-4c65-9e20-5a1c7d8b9034",
      "name": "EXAMPLE_CLOUD_PROFILE",
      "provider": "oss",
      "envSizeBytes": 10485760,
      "envSizeMB": "10.00",
      "localIds": [12, 35]
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "provider": "oss"
}

字段	类型	说明
success	boolean	列表查询成功时为 true。
data	object[]	当前页的云备份，按 cloudId ASCII 升序排列，可为空数组。
data[].cloudId	string	云备份标识，不是本地环境 ID。
data[].name	string	云端元数据中的名称，可能为空字符串。
data[].provider	string	所选提供方 oss 或 webdav。
data[].envSizeBytes	integer	云端元数据中的备份字节数，非负整数；缺失或无效时为 0。
data[].envSizeMB	string	envSizeBytes / 1024 / 1024，保留两位小数的字符串。
data[].localIds	integer[]	已绑定同一备份及提供方的本地环境正整数 ID；没有匹配项时为空数组。
total	integer	有效备份去重后、分页前的总数，不是当前页长度。
page、pageSize	integer	实际分页值；页码超出末页时 data 为空数组。
provider	string	整个响应实际使用的提供方。

名称和大小来自云端元数据，不是本地磁盘实时数据：OSS 使用云列表元数据，WebDAV 使用 .meta.json 中的名称及 .dat 对象报告的大小。localIds 同时匹配 cloudId 和提供方；WebDAV 还须匹配已配置的服务器、账号及基础目录，其他 WebDAV 配置中的同名云 ID 不算匹配。

localIds 只表示关联关系，不表示自动云同步已启用；恢复后关闭自动同步的环境仍可能出现在这里。

将 cloudId 传给从云端备份恢复。即使 localIds 非空，恢复接口也不会覆盖这些环境。

错误响应

新接口自身产生的错误使用以下结构：

{
  "success": false,
  "code": "INVALID_PARAMETERS",
  "error": "Invalid request parameters"
}

HTTP	code	说明
400	INVALID_PARAMETERS	未知 Query 参数或分页参数无效。
400	INVALID_PROVIDER	提供方不是严格的 oss 或 webdav。
400	WEBDAV_CONFIG_REQUIRED	客户端保存的 WebDAV 配置缺失或无效。
401	AUTH_REQUIRED / LOGIN_REQUIRED	需要登录客户端。缺失或无效的 api-key 也会由全局中间件返回 401。
403	VIP_REQUIRED	云同步 VIP 权限缺失或过期。缺少 local_api 授权也会由全局中间件返回 403。
409	CLOUD_SESSION_CHANGED	操作过程中切换了登录账号；再次请求前确认当前账号。
502	CLOUD_BACKUP_LIST_FAILED / WEBDAV_AUTH_FAILED	云列表查询失败，或已保存的 WebDAV 凭据认证失败。
503	CLOUD_SYNC_UNAVAILABLE	客户端云同步模块不可用。
504	REQUEST_TIMEOUT	检测到的云传输超时。

现有全局鉴权中间件可能只返回 success 和 error，没有 code。请同时检查 HTTP 状态与响应体，参见错误码与响应兼容。