Download a file by using the SDK for JavaScript - Drive and Photo Service

PDSClient provides two methods to download a single file: downloadFile and createDownloadTask. This topic describes how to use these two methods to download a file from Photo and Drive Service (PDS).

Note

Download a file on a web client:

Due to the limits of the browser API, an error may be reported if the browser cache is insufficient and it is difficult to identify the specific cause. Therefore, we recommend that you do not use the downloadFile or createDownloadTask method to download a file on a web client.

We recommend that you use the following methods to download files on a web client:

Download a single file
Call the listFiles or getFile method to obtain the value of the download_url parameter in the IFileItem object. Open the download URL in a browser to download the file. This method is suitable for the download of a single file rather than multiple files or files in a directory.
Download multiple files or files in a directory
Recursively traverse all files in a file list or a directory to obtain the value of the download_url parameter for each file. Download the files at the frontend and generate a ZIP package. This method is suitable for the download of multiple files or files in a directory. However, this method occupies a large amount of memory and is not suitable for the download of large files or directories.

downloadFile method

Downloads a file in a convenient way.

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

const cp = await client.downloadFile(pdsFile, downloadTo, options)

Example

// from
const pdsFile= {
  drive_id: '1',
  file_id: 'xxxxxxxx',
}

// to  (Note: If you download a file in a browser, you do not need to specify this parameter. In this case, use an empty string.)
const downloadTo = '/Users/test/a.txt'

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

// Download the file.
await client.downloadFile(pdsFile, downloadTo, options);

console.log('The download is complete.');

Request parameters

Parameter	Type	Required	Description
pdsFile	Partial<IDownCheckpoint>	Yes	The file to be downloaded, or the download checkpoint information.
downloadTo	string	Yes	The path to which the file is to be downloaded. If you download a file in a browser, you do not need to specify this parameter. In this case, use an empty string.
options	IDownloadOptions		The download configurations, including callback methods.

IDownCheckpoint parameters

Parameter	Type	Required	Description
path_type	string	Yes	The data storage mode of the domain. Set the value to `StandardMode`.
loc_id	string		The ID of the drive or share in which the file to be downloaded is stored. We recommend that you replace this parameter with the `drive_id` or `share_id` parameter.
loc_type	string		The location type of the file to be downloaded. This parameter is used together with the `loc_id` parameter. Valid values: `drive` and `share`.
file_key	string		The unique identifier of the file to be downloaded. You must specify one of the file_key and file_id parameters.
drive_id	string		The drive ID. You can specify only one of the `drive_id` and `share_id` parameters.
share_id	string		The share ID. You can specify only one of the `drive_id` and `share_id` parameters.
file_id	string		The ID of the file to be downloaded. You must specify one of the file_key and file_id parameters.
file	IFile	Yes	The file to be downloaded.
id	string		The ID of the download task.
download_id	string		The download ID. It is the ID that is generated if a local temporary file is created.
download_url	string		The download URL.
content_md5	string		The MD5 hash value of the file.
crc64ecma	string		The CRC-64 value of the file.
content_type	string		The content type of the file.
part_info_list	Array<IDownPartInfo>		The list of parts that are downloaded.
state	string		The state of the download task. Valid values: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`.
message	string		The error message.
progress	number		The progress of the download task. Valid values: 0 to 100.
loaded	number		The number of bytes that have been downloaded. Unit: `bytes`.
start_time	number		The time when the downloaded task started. Unit: `milliseconds`.
end_time	number		The time when the download task ended. Unit: `milliseconds`.
used_avg_speed	number		The average speed at which the file is downloaded. Unit: `bytes/s`.
used_time_len	number		The period of time that has been taken for the download task. Unit: `milliseconds`.

You can specify only one of the following parameters: loc_id together with loc_type, share_id, and drive_id.
You must specify one of the file_key and file_id parameters.

IDownloadOptions (extends IDownConfig) parameters

Parameter	Type	Required	Description
onReady	(task: UploadTask) => void		The callback method for the download task after the task is created.
onProgress	(state: string, progress:number) => void		The callback method that is used to listen for the task progress. You can use this method to listen for the download progress and the progress of calculating the CRC-64 value. Valid values of `state`: `running` and `checking`. A value of running specifies that the download task is in progress. A value of checking specifies that the CRC-64 value is being calculated. Valid values of `progress`: 0 to 100.
onStateChange	(cp: IDownCheckpoint, state: string, error?: PDSError) => void		The callback method that is used to listen for task status changes. Valid values of `state`: `waiting, start, created, running, stopped, complete, checking, success, error, and cancelled`.
onPartComplete	(cp:IDownCheckpoint, part: IPartInfo) => void		The callback method that is used to listen for the completion of part download.
... Other IDownConfig parameters			Other parameters.

IDownPartInfo parameters

Parameter	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.

IDownConfig parameters

Parameter	Type	Required	Description
verbose	boolean		Specifies whether to display debugging logs.
checking_crc	boolean		Specifies whether to perform cyclic redundancy check (CRC) verification. Default value: `true`.
chunk_con_auto	boolean		Specifies whether to automatically adjust the number of concurrent parts that are being downloaded.
init_chunk_con	number		The custom number of concurrent parts to download. This parameter takes effect only if you set the `chunk_con_auto` parameter to `false`.
max_chunk_size	number		The size of the part.

Response parameters

Parameter	Type	Required	Description
cp	IDownCheckpoint	Yes	The checkpoint information of the download task. In this case, the download task may be in the `success, error, stopped, or cancelled` state.

createDownloadTask method

Creates a download task.

const task = client.createDownloadTask(checkpoint, configs)

Example

const cp = {
  // to 
  file: {
    name: "a.txt",
    path: "/Users/zu/a.txt", // Note: If you download a file in a browser, you do not need to specify this parameter. 
    size: 100,
  },
  
  // from
  path_type: 'StandardMode',
  // loc_type: 'drive',  
  // loc_id: '1',        // This parameter can be replaced with the drive_id parameter.
  // file_key: 'xxxxxxxx'  // This parameter can be replaced with the file_id parameter.
  
  drive_id: '1',
  file_id: 'xxxxxxxx'
};

const task = client.createDownloadTask(cp);

Request parameters

Parameter	Type	Required	Description
checkpoint	IDownCheckpoint	Yes	The parameters that are used to create a download task.
configs	IDownConfig		The download configurations.

Response parameters

A DownloadTask instance is returned.

Parameter	Type	Required	Description
task	DownloadTask	Yes	The download task.

DownloadTask class

Creates a download task to download files.

Supported methods

.wait()

After you call this method, the download task enters the waiting state. The value of the state parameter changes to waiting.

.start()

You can call this method to start the download task. After you call this method, concurrent parts start to be downloaded.

task.start();

.stop()

You can call this method to stop the download task. After you call this method, the value of the state parameter changes to stopped. In this case, the client instance stores the checkpoint information for the next resumable download.

task.stop();

.cancel()

You can call this method to cancel the download task. After you call this method, the value of the state parameter changes to cancelled.

task.cancel()

.getCheckpoint()

You can call this method to query the checkpoint information of the download task. In addition to calling this method, you can query the checkpoint information by using event callbacks.

var cp = task.getCheckpoint()

.on(eventname, callback)

You can call this method to configure listeners.

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

Request parameters

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

Supported events

You can listen for the following events: progress, statechange, and partialcomplete.

Callback method for a progress event

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

Request parameters

Parameter

Type

Required

Description

state

string

Yes

The state of the download task.

Valid values of state: running and checking. A value of running specifies that the download task is in progress. A value of checking specifies that the CRC-64 value is being calculated.

progress

number

Yes

The progress of the download task. Valid values: 0 to 100.

Callback method for a statechange event

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

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

Callback method for a partialcomplete event

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

Parameter	Type	Required	Description
checkpoint	IDownCheckpoint	Yes	The checkpoint information of the download task.
partInfo	IDownPartInfo	Yes	The information about the parts that are downloaded.

States

The following table describes the possible states of a download task.

State	Description
waiting	The download task is waiting to start. By default, a download task enters this state after it is created. You can call the `wait()` method to trigger this state.
start	The download task starts. You can call the `start()` method to trigger this state.
created	The download task is created. This state is triggered after a local temporary file is created.
running	The download task is in progress.
stopped	The download task is stopped.
complete	The download task is complete but the file is not verified.
checking	The `CRC-64` verification is being performed on the file.
success	The download task is successful.
error	The download 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 download process.
cancelled	The download task is canceled. You can call the `.cancel()` method to trigger this state.

Parameters that may be used

Parameter	Type	Description
speed	number	The download speed. Unit: `byte/s`. This parameter is valid only if the state of the task is running.
progress	number	The progress of the download task. Valid values: 0 to 100.
loaded	number	The size of the parts that have been downloaded. Unit: `bytes`.
file	IFile	The information about the file.
left_time	number	The approximate period of time required for the remaining parts. Unit: `seconds`.
start_time	number	The time when the download task started. Unit: `milliseconds`.
end_time	number	The time when the download task ended. Unit: `milliseconds`.
used_avg_speed	number	The average download speed. Unit: `byte/s`.
used_time_len	number	The duration of the download. Unit: `milliseconds`.