使用Javascript SDK在Node.js下載檔案-網盤與相簿服務-阿里雲

PDSClient 提供2種下載單個檔案方法： downloadFile 和 createDownloadTask，目前僅支援 Node.js 環境（或 Electron ）。下面分別介紹。

說明

關於Web端下載：

Web 端和案頭端下載檔案不一樣。web 端的下載有3種方式，下面分別介紹下。

第一種：listFiles/getFile 返回的檔案 IFileItem 裡有個 download_url 欄位，可以用瀏覽器直接開啟下載。這種方式只能下載單個檔案，不能下載多個檔案或目錄。

第二種：開通服務端打包下載的增值服務，調用 client.pollingArchiveFile() 方法，拿到 url 欄位後用瀏覽器直接開啟下載。這種方式可以下載多個檔案和目錄。

第三種：遞迴遍曆檔案清單和目錄中的每個檔案的 download_url，在前端下載並 zip。這種方式可以下載多個檔案和目錄，但是佔用記憶體較大，不適合下載較大檔案或目錄。

Web 端下載，推薦使用第一和第二種結合的方式。單個檔案用第一種，多個檔案或目錄用第二種。

downloadFile 方法

下載檔案便捷方法。

重要

此方法僅支援 Node.js 環境（或Electron）。

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
const downloadTo = '/Users/test/a.txt'

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

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

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

參數說明

欄位	類型	必選	說明
pdsFile	IDownCheckpoint	是	下載來源物件。或者下載斷點資訊。
downloadTo	string	是	本地檔案路徑。
options	IDownloadOptions		下載配置（包括回調方法等）。

IDownCheckpoint 欄位說明

欄位	類型	必選	說明
path_type	string	是	domain 的 `path_type` 屬性。取值範圍： `StandardMode`, `HostingMode`。
loc_id	string		（不推薦，請使用`drive_id` 或者 `share_id` 替代）下載檔案所在的 `drive_id` 或者 `share_id`。
loc_type	string		下載檔案所在的類型配合 `loc_id` 使用，取值範圍： "`drive`" 或者 "`share`"。
file_key	string		下載檔案唯一標識。標準模式為目錄ID，託管模式為目錄Path。
drive_id	string		雲端硬碟ID。 `drive_id`和`share_id`互斥，只需傳一個即可。
share_id	string		（託管模式有效）共用ID。`drive_id`和`share_id`互斥，只需傳一個即可。
file_id	string		要下載的檔案ID（標準模式）。`file_id` 和`file_path` 互斥，只需傳一個即可。
file_path	string		要下載的檔案路徑（託管模式）。`file_id` 和`file_path` 互斥，只需傳一個即可。
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 || file_path 傳入一組即可。

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 方法

建立一個下載任務。

重要

此方法僅支援 Node.js 環境（或Electron）。

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` 。