Upload a file - Drive and Photo Service - Alibaba Cloud Documentation Center

PDSClient provides two methods to upload a file: uploadFile and createUploadTask. This topic describes the two methods.

uploadFile method

Uploads a file in a convenient way.

The await keyword can be used to wait until the file is uploaded.
If the value of state is stopped, cancelled, or error, PDSError is thrown.

// client indicates a PDSClient instance.
const cp = await client.uploadFile(from, uploadTo, options)

Example

<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("Uploaded");
  }
</script>

Request parameters

Parameter	Type	Required	Description
file	IFile \| string	Yes	The file to be uploaded. If you want to upload a file in a web browser, specify the HTML file that you want to upload. If you want to upload a file in the Node.js environment, set the value to the local file path or the local path information.
uploadTo	IUpCheckpoint	Yes	The information about the Drive and Photo Service (PDS) directory to which the file is to be uploaded. You can also set the value to the last checkpoint information.
options	IUploadOptions		The upload configurations, including callback methods.

Fields of IFile

Field	Type	Required	Description
path	string	Yes	The path.
name	string	Yes	The name of the file.
size	number	Yes	The size of the file.
type	string		The `content type` of the file.

Fields of IUpCheckpoint

Field	Type	Required	Description
file	IFile	Yes	The file to be uploaded. If you want to upload a file in a web browser, specify the HTML file that you want to upload. If you want to upload a file in the Node.js environment, set the value to the local path information.
path_type	string	Yes	The `path type` of the domain. Set the value to `StandardMode`.
loc_id	string		The ID of the location to which the file is to be uploaded. It can be a `drive_id` or `share_id`.
loc_type	string		The type of the location to which the file is to be uploaded. Valid values: `drive` and `share`.
parent_file_key	string		The ID of the directory to which the file is to be uploaded. We recommend that you replace this parameter with the `parent_file_id` parameter.
drive_id	string		The drive ID of the directory to which the file is to be uploaded. You muse specify one of the `drive_id` and `share_id` parameters.
share_id	string		The share ID of the directory to which the file is to be uploaded. You must specify one of the `drive_id` and `share_id` parameters.
parent_file_id	string		The parent directory ID of the directory to which the file is to be uploaded.
new_name	string		The new name to be used for the uploaded file. This parameter may be affected by the `check_name_mode` parameter.
id	string		The ID of the upload task.
file_key	string		The ID of the file to be uploaded. We recommend that you replace this parameter with the file_id parameter.
update_id	string		The upload ID. This ID is generated after PDS creates a temporary file.
part_info_list	Array<IUpPartInfo>		The list of parts that are to be uploaded.
state	string		The state of the upload task. Valid values: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, and cancelled`.
message	string		The error message.
progress	number		The upload progress. Valid values: 0 to 100.
loaded	number		The number of bytes that have been uploaded. Unit: `bytes`.
chunk_size	number		The size of a part. Unit: `bytes`.
start_time	number		The start time of the upload task. Unit: `millisecond`.
end_time	number		The end time of the upload task. Unit: `millisecond`.
used_avg_speed	number		The average speed at which the file is uploaded. Unit: `bytes/s`.
used_time_len	number		The period of time that has elapsed since the start of the upload task. Unit: `millisecond`.

You must specify loc_id + loc_type or share_id || drive_id.
You must specify parent_file_key or parent_file_id.

Fields of IUploadOptions (extends IUpConfig)

Field	Type	Required	Description
onReady	(task: UploadTask) => void		The callback method for the `upload task` after the task is created.
onProgress	(state: string, progress:number) => void		The callback method that is used to listen to the progress. You can use this method to listen to the progress of calculating the SHA-1 hash value, the upload progress, or the progress of calculating the CRC-64 value. Valid values of `state`: `computing_hash`, `running`, and `checking`. A value of computing_hash indicates that the SHA-1 hash value is being calculated. A value of running indicates that the upload task is in progress. A value of checking indicates that the CRC-64 value is being calculated. Valid values of `progress`: 0 to 100.
onStateChange	(cp: IUpCheckpoint, state: string, error?: PDSError) => void		The callback method that is used to listen to task state changes. Value values of state: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, and cancelled`
onPartComplete	(cp:IUpCheckpoint, part: IPartInfo) => void		The callback method that is used to listen to the completion of part upload.
... Other IUpConfig fields

Fields of IUpPartInfo

Field	Type	Required	Description
part_number	number	Yes	The sequence number of the part. The number starts from 1.
part_size	number	Yes	The size of the part.
etag	string		The `ETag` that is generated after the part is uploaded.

Fields of IUpConfig

Field	Type	Required	Description
parallel_upload	boolean		Specifies whether to concurrently upload parts. Default value: `false`.
check_name_mode	string		The policy that is used when a new file has the same name as an existing file. Valid values: `overwrite`: overwrites an existing file with a file that has the same name as the existing file. `auto_rename`: adds a random number to the end of the file name. `refuse`: does not create a file that has the same name as the existing file. `ignore`: creates a file that has the same name as the existing file.
checking_crc	boolean		Specifies whether to perform CRC verification. Default value: `true`.
chunk_con_auto	boolean		Specifies whether to automatically adjust the number of concurrent parts that are being uploaded.
init_chunk_con	number		The custom number of concurrent parts to be uploaded. This field takes effect only if `chunk_con_auto` is set to `false`.
max_chunk_size	number		The size of the part.
ignore_rapid	boolean		Specifies whether to forcibly disable instant file transfer. Default value: `false`. This field can be used for testing.

Response parameters

Parameter	Type	Required	Description
cp	IUpCheckpoint	Yes	The checkpoint information of the upload task. Valid states include `success`, `rapid_success`, `error`, `stopped`, and `cancelled`.

createUploadTask method

Creates an upload task.

const task = client.createUploadTask(checkpoint, configs)

Example

<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", // You can replace this parameter with the drive_id parameter.
      // loc_type: "drive",
      // parent_file_key: "root", // You can replace this parameter with the parent_file_id parameter.
      
      drive_id: "1", 
      parent_file_id: "root"
    };
  
    // Create an upload task.
    const task = client.createUploadTask(cp);
    
    // Listen to the upload progress.
    task.on('progress', (state, progress)=>{
       console.log(state, progress);
    });
  
    // Start the upload task.
    task.start();
   
    // ...
  }
</script>

Request parameters

Parameter	Type	Required	Description
checkpoint	IUpCheckpoint	Yes	The upload attributes.
configs	IUpConfig		The upload configurations.

Response parameters

Parameter	Type	Required	Description
task	UploadTask	Yes	The UploadTask instance.

UploadTask class

Creates a task to upload a file.

Supported methods

.wait()

After you call this method, the state of the task changes to waiting.

.start()

You can call this method to start an upload task. After you start the upload task, the system starts to calculate the SHA-1 hash value. If the file is instantly uploaded, a message is returned, which indicates a successful instant file transfer. If the file cannot be instantly uploaded, the system starts to upload the file by uploading parts of the file. The config.parallel_upload parameter specifies whether to concurrently upload parts.

task.start();

.stop()

You can call this method to suspend an upload task. The state of the task changes to stopped. In this case, the client instance stores the checkpoint information for the next resumable upload.

task.stop();

.cancel()

You can call this method to cancel an upload task. The state of the task changes to cancelled.

task.cancel()

.getCheckpoint()

You can call this method to query the checkpoint information of the upload task. Alternatively, you can query the checkpoint information of the task by using event callbacks.

IUpCheckpoint cp = task.getCheckpoint()

.on(eventname, callback)

You can call this method to configure listeners.

// Example: progress event
task.on('progress', (state, progress)=>{
   console.log(state, progress)
})

Parameters

Parameter	Type	Required	Description
eventname	ICheckpoint	Yes	The name of the event. Valid values: `progress`, `statechange`, and `partialcomplete`.
callback	Function	Yes	The callback function.

Supported events

Callback method for a progress event

You can listen to events of the following types: progress, statechange, and partialcomplete.

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

Parameters

Parameter

Type

Required

Description

state

string

Yes

The state of the task.

Valid values: computing_hash, running, and checking. A value of computing_hash indicates that the SHA-1 hash value is being calculated. A value of running indicates that the upload task is in progress. A value of checking indicates that the CRC-64 value is being calculated.

progress

number

Yes

The upload progress. Valid values: 0 to 100.

Callback method for a statechange event

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

Parameter	Type	Required	Description
checkpoint	IUpCheckpoint	Yes	The checkpoint information of the upload task.
state	string	Yes	The state of the upload task. Valid values: `waiting, start, computing_hash, created, running, stopped, complete, checking, success, rapid_success, error, and cancelled`.
error	PDSError		The upload error. A value is returned if the state of the task is `error`, `stopped`, or `cancelled`.

Callback method for a partialcomplete event

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

Parameter	Type	Required	Description
checkpoint	IUpCheckpoint	Yes	The checkpoint information of the upload task.
partInfo	IUpPartInfo	Yes	The information about the parts that are uploaded.

States

An upload task can be in one of the following states.

State	Description
waiting	The upload task is waiting to start. By default, an upload task is in this state after it is created. You can call the `wait()` method to trigger this state.
start	The upload task starts. You can call the `start()` method to trigger this state.
created	The upload task is created. This state is triggered after PDS creates a temporary file. In this case, an `upload ID` is generated.
computing_hash	The `SHA-1` hash value is being calculated, which is used for instant file transfer. If the file is instantly uploaded, the state of the task changes to `rapid_success`.
running	The upload task is running.
stopped	The upload task is suspended.
complete	The upload task is complete but the file is not verified.
checking	The `CRC-64` verification is being performed on the file.
success	The upload task is successful.
rapid_success	The file is instantly uploaded.
error	The upload task fails. This state is triggered if an API operation fails to be called, a network connection fails, or a local I/O operation fails during the upload process.
cancelled	The upload task is canceled. You can call the `.cancel()` method to trigger this state.

Parameters that may be used

// Example:
console.log(task.speed)

Parameter	Type	Description
speed	number	The upload speed. Unit: `byte/s`. This parameter is valid only if the state of the task is running.
progress	number	The upload progress. Valid values: 0 to 100.
loaded	number	The size of the parts that have been uploaded. Unit: `bytes`.
file	IFile	The information about the file.
left_time	number	The approximate amount of time that is required for uploading the remaining parts. Unit: `seconds`.
start_time	number	The start time of the upload task. Unit: `millisecond`.
end_time	number	The end time of the upload task. Unit: `millisecond`.
used_avg_speed	number	The average upload speed. Unit: `byte/s`.
used_time_len	number	The duration of the upload. Unit: `millisecond`.