上传文件_网盘与相册服务(PDS)-阿里云帮助中心

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`, `HostingMode`。
loc_id	string		上传目的地ID，可以为 `drive_id` 或者 `share_id`。
loc_type	string		上传目的地类型，取值范围："`drive`" 或者 "`share`"。
parent_file_key	string		（不推荐，请使用`parent_file_id` 或者 `parent_file_path` 替代）上传目的地目录ID。标准模式为目录ID，托管模式为目录Path。
drive_id	string		上传目的地的云盘ID。 `drive_id`和`share_id`互斥，只需传一个即可。
share_id	string		（托管模式有效）上传目的地的共享ID。`drive_id`和`share_id`互斥，只需传一个即可。
parent_file_id	string		上传目的地的父目录ID（标准模式有效）。
parent_file_path	string		上传目的地的父目录路径（托管模式有效）。
new_name	string		重命名（标准模式有效）。会受`check_name_mode` 参数影响。
id	string		上传任务ID。
file_key	string		文件ID（标准模式）或者Path（托管模式）。
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 || parent_file_path 也是只需传一对即可。

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		强制不秒传。（标准模式下有效，可用来测试）

字段	类型	必选	说明
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()

开始任务。如果是在标准模式的domain下，开始计算秒传信息，如果能秒传则返回秒传成功，如果不能，则开始分片上传（是否并发上传取决于参数config.parallel_upload）。如果是托管模式下，会直接开始分片并发上传。

task.start();

.stop()

暂停（停止）任务。state 改为 stopped。此时客户端可以将 checkpoint 信息存储起来，供下次断点续传。

task.stop();

.cancel()

取消任务。 state 将改为 cancelled。

task.cancel()

.getCheckpoint()

获取 checkpoint 信息。除了调用此方法，还可以通过事件回调拿到 checkpoint 信息。

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