文档

上传文件

更新时间:

PDSClient 提供2种上传文件方法: uploadFile 和 createUploadTask。 下面分别介绍。

uploadFile 方法

上传文件便捷方法。

  • await 会等待上传完成。

  • statestopped, cancellederror 时,会 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。标准模式为目录ID,托管模式为目录Path。

drive_id

string

上传目的地的云盘ID。 drive_idshare_id互斥,只需传一个即可。

share_id

string

上传目的地的分享ID。drive_idshare_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_typeshare_id || drive_id 只需传一对即可。

  • parent_file_keyparent_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_autofalse 时生效。

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

  • 本页导读 (0)
文档反馈