如何通過JavascriptSDK上傳檔案 - Drive and Photo Service

PDSClient 提供2種上傳檔案方法： uploadFile 和 createUploadTask。下面分別介紹。

uploadFile 方法

上傳檔案便捷方法。

await 會等待上傳完成。
state 為 stopped, cancelled 和 error 時，會 throw PDSError。

// client 是 PDSClient 執行個體
const cp = await client.uploadFile(from, uploadTo, options)

舉例

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let uploadTo = {drive_id: '1', parent_file_id: 'root'};
    await client.uploadFile(file, uploadTo);
    console.log("上傳成功");
  }
</script>

參數說明

欄位	類型	必選	說明
file	IFile \| string	是	要上傳的檔案。瀏覽器：HTML File 對象。 node.js: 本地檔案路徑，或者本地檔案資訊。
uploadTo	IUpCheckpoint	是	上傳目的地的 pds 目錄資訊。或者上次的斷點資訊。
options	IUploadOptions		上傳配置（包括回調方法等）。

IFile 欄位說明

欄位	類型	必選	說明
path	string	是	路徑。
name	string	是	檔案名稱。
size	number	是	檔案大小。
type	string		檔案的 `Content-Type`。

IUpCheckpoint 欄位說明

欄位	類型	必選	說明
file	IFile	是	上傳檔案對象。瀏覽器：HTML File 對象。 node.js: 本地檔案資訊。
path_type	string	是	domain 的 `path_type` 屬性。取值範圍：`StandardMode`。
loc_id	string		上傳目的地ID，可以為 `drive_id` 或者 `share_id`。
loc_type	string		上傳目的地類型，取值範圍："`drive`" 或者 "`share`"。
parent_file_key	string		（不推薦，請使用`parent_file_id` 替代）上傳目的地目錄ID。
drive_id	string		上傳目的地的雲端硬碟ID。 `drive_id`和`share_id`必傳其一。
share_id	string		上傳目的地的分享ID。`drive_id`和`share_id`必傳其一。
parent_file_id	string		上傳目的地的父目錄ID。
new_name	string		重新命名。會受`check_name_mode` 參數影響。
id	string		上傳任務ID。
file_key	string		（不推薦，請使用 file_id 替代）檔案ID。
update_id	string		上傳ID。PDS服務建立好臨時檔案會產生此ID。
part_info_list	Array<IUpPartInfo>		上傳分區資訊。
state	string		上傳任務狀態，取值範圍：`waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, cancelled`。
message	string		報錯資訊。
progress	number		上傳進度資訊。取值0-100。
loaded	number		已經上傳的位元組數 (`Bytes`) 。
chunk_size	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 只需傳一對即可。
parent_file_key 和 parent_file_id 也是只需傳一種即可。

IUploadOptions (extends IUpConfig)

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

IUpPartInfo 欄位說明

欄位	類型	必選	說明
part_number	number	是	分區序號，從1開始。
part_size	number	是	分區大小。
etag	string		分區上傳成功後的`ETag`。

IUpConfig 欄位說明

欄位	類型	必選	說明
parallel_upload	boolean		是否並發上傳。預設：`false`。
check_name_mode	string		取之範圍： `overwrite`（直接覆蓋） `auto_rename`（在原來名稱後增加隨機字串） `refuse`（不會建立） `ignore`（會建立重名的）
checking_crc	boolean		是否進行crc校正, 預設：`true`。
chunk_con_auto	boolean		是否自動調整並發數
init_chunk_con	number		自訂指定並發數，`chunk_con_auto`為`false` 時生效。
max_chunk_size	number		分區大小。
ignore_rapid	boolean		強制不秒傳，預設 `false`。（可用來測試）

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

createUploadTask 方法

建立一個上傳任務。

const task = client.createUploadTask(checkpoint, configs)

舉例

<input type="file" id="f1"/>

<script> 
  document.getElementById('f1').onchange = async function(e){
    let file = e.target.files[0];
    let cp = {
      
      // from
      file,
      
      // to
      path_type: "StandardMode",
      // loc_id: "1",    // 可以使用 drive_id 替代
      // loc_type: "drive",
      // parent_file_key: "root", // 可以使用 parent_file_id 替代
      
      drive_id: "1", 
      parent_file_id: "root"
    };
  
    // 建立上傳任務
    const task = client.createUploadTask(cp);
    
    // 監聽進度
    task.on('progress', (state, progress)=>{
       console.log(state, progress);
    });
  
    // 開始上傳
    task.start();
   
    // ...
  }
</script>

參數說明

欄位	類型	必選	說明
checkpoint	IUpCheckpoint	是	上傳參數。
configs	IUpConfig		上傳配置。

返回 UploadTask 執行個體。

欄位	類型	必選	說明
task	UploadTask	是	上傳任務執行個體。

UploadTask 類介紹

用於建立一個上傳檔案任務。

支援方法

.wait()

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

.start()

開始任務。開始計算秒傳資訊，如果能秒傳則返回秒傳成功，如果不能，則開始分區上傳（是否並發上傳取決於參數config.parallel_upload）。

task.start();

.stop()

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

task.stop();

.cancel()

取消任務。 state 將改為 cancelled。

task.cancel()

.getCheckpoint()

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

IUpCheckpoint cp = task.getCheckpoint()

.on(eventname, callback)

事件監聽。

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

參數說明

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

支援的事件

progress 事件回調

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

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

參數說明

欄位

類型

必選

說明

state

string

是

任務狀態。

state 可能值為：computing_hash（計算秒傳）,running（正在上傳）, checking（計算crc64）。

progress

number

是

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

statechange 事件

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

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

partialcomplete 事件

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

欄位	類型	必選	說明
checkpoint	IUpCheckpoint	是	上傳斷點資訊。
partInfo	IUpPartInfo	是	當前完成的分區資訊。

state 狀態說明

上傳任務狀態有 12 種：

狀態	說明
waiting	等待中。任務建立後的預設狀態。調用 `wait()` 方法觸發。
start	開始上傳。調用 `start()` 方法觸發。
created	建立 PDS 臨時檔案後觸發。此時產生 `upload_id`。
computing_hash	開始計算 `sha1`，用於秒傳。如果秒傳成功，狀態直接變為 `rapid_success`。
running	上傳中。
stopped	暫停上傳。
complete	上傳完成，未校正檔案正確性。
checking	校正檔案正確性（`crc64`）。
success	上傳成功。
rapid_success	秒傳成功。
error	上傳任務失敗。上傳過程中調用介面失敗（包括網路錯誤），或者本地IO操作失敗，均會觸發。
cancelled	上傳任務取消。調用 `.cancel()` 方法才會觸發。

可能會用到的屬性

// 舉例：
console.log(task.speed)

狀態	類型	說明
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` 。