列出雲端備份

查詢目前客戶端登入帳號及所選儲存提供者的備份。此介面不會讀取本機環境目錄的即時大小，也不會還原環境。

請求

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 狀態及回應內容，參見錯誤碼與回應相容。