通過JavascriptSDK下載檔案 - Drive and Photo Service

PDSClient提供了downloadFile和createDownloadTask兩種下載單個檔案的方法。本文將介紹如何利用這兩種方法來從PDS服務中下載檔案。

說明

關於Web端下載：

在使用Web端下載檔案時，由於瀏覽器API的限制，當瀏覽器緩衝不足時可能會報錯且難以擷取具體原因，因此目前不建議使用downloadFile和createDownloadTask兩種方式進行Web端下載檔案操作。

使用Web端下載檔案時，推薦使用以下方式進行操作。

單個檔案下載：
使用listFiles方法或getFile方法方法擷取的檔案IFileItem對象中包含download_url欄位，可以直接在瀏覽器中開啟該URL進行下載。此方法適用於單個檔案的快速下載，不適用於批量檔案或目錄。
多個檔案或目錄下載：
遞迴遍曆檔案清單和目錄中的每個檔案的download_url，在前端下載並壓縮成zip檔案。這種方法適用於下載多個檔案或整個目錄，但會佔用較大的記憶體，不適合下載大型檔案或目錄。

downloadFile方法

下載檔案便捷方法。

await 會等待下載完成。
state為stopped，cancelled和error時，會throw PDSError。

const cp = await client.downloadFile(pdsFile, downloadTo, options)

舉例

// from
const pdsFile= {
  drive_id: '1',
  file_id: 'xxxxxxxx',
}

// to  (注意，如果是瀏覽器端下載，這個欄位無效，一般傳入Null 字元串""即可)
const downloadTo = '/Users/test/a.txt'

const options = {
  onProgress(state, progress){
    console.log(state, progress)
  }
}

// 下載
await client.downloadFile(pdsFile, downloadTo, options);

console.log('下載完成');

參數說明

欄位	類型	必選	說明
pdsFile	Partial<IDownCheckpoint>	是	下載來源物件。或者下載斷點資訊。
downloadTo	string	是	本地檔案路徑。如果是瀏覽器端下載，這個欄位無效，一般傳入Null 字元串""即可。
options	IDownloadOptions		下載配置（包括回調方法等）。

IDownCheckpoint欄位說明

欄位	類型	必選	說明
path_type	string	是	domain 的`path_type`屬性。取值範圍：`StandardMode`。
loc_id	string		（不推薦，請使用`drive_id`或者`share_id`替代）下載檔案所在的`drive_id`或者`share_id`。
loc_type	string		下載檔案所在的類型配合`loc_id`使用，取值範圍： "`drive`" 或者 "`share`"。
file_key	string		下載檔案唯一標識。file_key和file_id 必選其一。
drive_id	string		雲端硬碟ID。`drive_id`和`share_id`互斥，只需傳一個即可。
share_id	string		分享ID。`drive_id`和`share_id`互斥，只需傳一個即可。
file_id	string		要下載的檔案ID。file_key和file_id 必選其一。
file	IFile	是	下載目的的本地檔案對象。
id	string		下載任務ID
download_id	string		下載ID。本地臨時檔案建立成功，會產生此ID。
download_url	string		下載url
content_md5	string		檔案的`MD5`值
crc64ecma	string		檔案的`crc64`值
content_type	string		檔案的`content-type`
part_info_list	Array<IDownPartInfo>		下載分區資訊
state	string		下載任務狀態，取值範圍：`waiting，start，created，running，stopped，complete， checking，success，error，cancelled`
message	string		報錯資訊。
progress	number		下載進度資訊。取值0-100。
loaded	number		已經下載的位元組數 (`Bytes`)
start_time	number		開始下載時間（單位：`ms`）
end_time	number		結束下載時間（單位：`ms`）
used_avg_speed	number		平均速度（單位：`Bytes/s`）
used_time_len	number		已用時間長度（單位：`ms`）

loc_id & loc_type 和 share_id || drive_id 傳入一組即可。
file_key 和 file_id 傳入一種即可。

IDownloadOptions (extends IDownConfig)

欄位	類型	必選	說明
onReady	(task: UploadTask) => void		UploadTask建立好後回調方法。
onProgress	(state: string, progress:number) => void		監聽進度變化的回調方法。支援下載進度，計算`crc64`進度的監聽。 `state`的取值範圍為：`running`（正在下載）, `checking`（計算`crc64`）。 `progress`取值範圍：0 - 100。
onStateChange	(cp: IDownCheckpoint, state: string, error?: PDSError) => void		監聽任務狀態變化的回調方法。 `state`取值範圍：`waiting， start，created，running，stopped，complete，checking，success，error，cancelled`
onPartComplete	(cp:IDownCheckpoint, part: IPartInfo) => void		監聽分區上傳完成的回調方法。
... IDownConfig 其他欄位			其他欄位

IDownPartInfo欄位說明

欄位	類型	必選	說明
part_number	number	是	分區序號，從1開始
part_size	number	是	分區大小

IDownConfig欄位說明

欄位	類型	必選	說明
verbose	boolean		是否列印調試日誌
checking_crc	boolean		是否進行`crc`校正, 預設：`true`
chunk_con_auto	boolean		是否自動調整並發數
init_chunk_con	number		自訂指定並發數，`chunk_con_auto`為`false` 時生效
max_chunk_size	number		分區大小

欄位	類型	必選	說明
cp	IDownCheckpoint	是	任務的斷點資訊。此時（任務）斷點的狀態，可能為`success, error, stopped, cancelled`。

createDownloadTask方法

建立一個下載任務。

const task = client.createDownloadTask(checkpoint, configs)

舉例

const cp = {
  // to 
  file: {
    name: "a.txt",
    path: "/Users/zu/a.txt", // 注意：瀏覽器中此欄位無效。
    size: 100,
  },
  
  // from
  path_type: 'StandardMode',
  // loc_type: 'drive',  
  // loc_id: '1',        // 可以使用 drive_id 替代
  // file_key: 'xxxxxxxx'  // 可以使用 file_id 替代
  
  drive_id: '1',
  file_id: 'xxxxxxxx'
};

const task = client.createDownloadTask(cp);

參數說明

欄位	類型	必選	說明
checkpoint	IDownCheckpoint	是	下載參數
configs	IDownConfig		下載配置

返回DownloadTask執行個體。

欄位	類型	必選	說明
task	DownloadTask	是	下載任務執行個體

DownloadTask類介紹

用於建立一個下載檔案任務。

支援方法

.wait()

調用後，任務將進入等待中狀態。state改為waiting。

.start()

開始任務。直接開始分區並發下載。

task.start();

.stop()

暫停（停止）任務。state改為stopped。此時用戶端可以將checkpoint資訊儲存起來，供下次斷點續傳。

task.stop();

.cancel()

取消任務。state將改為cancelled。

task.cancel()

.getCheckpoint()

擷取checkpoint資訊。除了調用此方法，還可以通過事件回調拿到checkpoint資訊。

var cp = task.getCheckpoint()

.on(eventname, callback)

事件監聽。

// 舉例 
task.on('progress', (state, progress)=>{    
   console.log(state, progress) 
})

參數說明

欄位	類型	必選	說明
eventname	string	是	事件名稱，目前支援：`progress, statechange, partialcomplete`。
callback	Function	是	回呼函數

支援的事件

目前支援的事件： progress, statechange, partialcomplete。

progress事件回呼函數

task.on('progress', (state, progress)=>{    
})

參數說明

欄位

類型

必選

說明

state

string

是

任務狀態。

state 可能值為：running（正在下載）, checking（計算crc64）。

progress

number

是

進度，取值範圍： 0 - 100。

statechange事件

task.on('statechange', (checkpoint, state, error)=>{    
})

欄位	類型	必選	說明
checkpoint	IDownCheckpoint	是	下載斷點資訊。
state	string	是	下載任務狀態，取值範圍：`waiting，start，created，running，stopped，complete，checking，success，error，cancelled`
error	PDSError		下載錯誤。狀態為 `error`, `stopped`, `cancelled`時可能有值。

partialcomplete事件

task.on('partialcomplete', (checkpoint, partInfo)=>{    
})

欄位	類型	必選	說明
checkpoint	IDownCheckpoint	是	下載斷點資訊。
partInfo	IDownPartInfo	是	當前完成的分區資訊。

state狀態說明

下載任務狀態有 10 種：

狀態	說明
waiting	等待中。任務建立後的預設狀態。調用 `wait()` 方法觸發。
start	開始下載。調用 `start()` 方法觸發。
created	建立本地臨時檔案後觸發。
running	下載中。
stopped	暫停下載。
complete	下載完成，未校正檔案正確性。
checking	校正檔案正確性（`crc64`）。
success	下載成功。
error	任務失敗。下載過程中調用介面失敗（包括網路錯誤），或者本地 IO 操作失敗，均會觸發。
cancelled	任務取消。調用 `.cancel()` 方法才會觸發。

可能會用到的屬性

狀態	類型	說明
speed	number	下載速度，單位 `Byte/s`。狀態為running時有效。
progress	number	進度。取值 0-100。
loaded	number	已經下載的大小。單位 `Byte`。
file	IFile	檔案資訊。
left_time	number	大約的剩餘時間，單位 `s`。
start_time	number	開始時間。單位 `ms`。
end_time	number	結束時間。單位 `ms`。
used_avg_speed	number	統計的平均下載速度，單位 `Byte/s`。
used_time_len	number	統計的耗時，單位 `ms` 。