Help Center/ Object Storage Service/ SDK Reference/ Node.js/ Object Download (SDK for Node.js)/ Downloading an Object - Resumable (SDK for Node.js)
Updated on 2024-11-13 GMT+08:00
View PDF
Share

Downloading an Object - Resumable (SDK for Node.js)

If you have any questions during development, post them on the Issues page of GitHub.

Function

The API for resumable download is an encapsulated and enhanced version of range-based download. Downloading large files often fails due to an unstable network or program breakdown. It is a waste of resources to restart the download process upon a download failure, and the restarted download process may still suffer from the unstable network. To resolve such issues, you can use the API for resumable download, whose working principle is to divide the to-be-downloaded file into multiple parts and download them separately. The download result of each part is recorded in a checkpoint file in real time. Only when all parts are successfully downloaded, the result indicating a successful download will be returned. Otherwise, an error is returned in callback function to remind you of calling the API again for re-downloading. Based on the download status of each part recorded in the checkpoint file, the re-downloading will download the parts failed to be downloaded previously, instead of downloading all parts. By virtue of this, resources are saved and efficiency is improved.

By resuming a failed download from where it failed, this API helps save resources. In addition, parts can be downloaded concurrently, which helps speed up the download. During the download process, you do not need to take care of internal service details, such as the creation and deletion of checkpoint files, division of objects, or concurrent downloads of parts.

Restrictions

Method

ObsClient.downloadFile(params)

Request Parameters

Table 1 List of request parameters

Parameter

Type

Mandatory (Yes/No)

Description

Bucket

string

Yes

Explanation:

Bucket name

Restrictions:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets with the same name in the same region, no error will be reported, and the bucket attributes comply with those set in the first creation request.

Value range:

The value can contain 3 to 63 characters.

Default value:

None

Key

string

Yes

Explanation:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path of the object that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Restrictions:

None

Value range:

The value can contain 1 to 1,024 characters.

Default value:

None

VersionId

string

No

Explanation:

Object version ID, for example, G001117FCE89978B0000401205D5DC9A

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

DownloadFile

string

No

Explanation:

The full local path that the object is downloaded to. If this parameter is not specified, the working directory of the current program is used.

Restrictions:

A file name must be included in the path, for example, aa/bb.txt.

Value range:

None

Default value:

None

PartSize

number

No

Explanation:

Size of the current part.

Restrictions:

None

Value range:

The value ranges from 100 KB to 5 GB, in bytes.

Default value:

102400

TaskNum

number

No

Explanation:

Maximum number of parts that can be downloaded concurrently

Restrictions:

None

Value range:

1~10000

Default value:

1, indicating concurrent downloads are not used.

ProgressCallback

function

No

Explanation:

Callback function for obtaining the download progress

NOTE:

This callback function contains the following parameters in sequence: number of downloaded bytes, total bytes, and used time (unit: second).

Restrictions:

None

Value range:

None

Default value:

None

ResumeCallback

function

No

Explanation:

Callback function used to obtain the control parameter for canceling a resumable download

Restrictions:

None

Value range:

None

Default value:

None

NOTE:
  • This callback function contains a control parameter used for canceling resumable downloads.
  • By calling the cancel method of this control parameter, you can pause a resumable download.

EnableCheckpoint

boolean

No

Explanation:

Whether to enable the resumable mode.

Restrictions:

None

Value range:

  • true: The resumable mode is enabled.
  • false: The resumable mode is disabled. In this case, this API works as a multipart download API, and no checkpoint files are generated.

Default value:

false

CheckpointFile

string

No

Explanation:

Path of a file generated for recording the progress of a resumable download. The file contains the information about parts and progress.

Restrictions:

This parameter is valid only in the resumable mode.

Value range:

None

Default value:

If this parameter is left blank, the checkpoint file will be in the same directory as the local path that the file is downloaded to.

IfMatch

string

No

Explanation:

Preset ETag. If the ETag of the object to be downloaded is the same as the preset ETag, the object is returned. Otherwise, an error is returned.

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

IfModifiedSince

string

No

Explanation:

If the object was modified after the time specified by this parameter, its content is returned. Otherwise, an error code is returned.

Restrictions:

The value must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.

Value range:

None

Default value:

None

IfNoneMatch

string

No

Explanation:

Preset ETag. If the ETag of the object to be downloaded is different from the preset ETag, the object is returned. Otherwise, an error is returned.

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

IfUnmodifiedSince

string

No

Explanation:

If the object was modified before the time specified by this parameter, its content is returned. Otherwise, an error code is returned.

Restrictions:

The value must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt.

Value range:

None

Default value:

None

SseC

string

Yes when SSE-C is used

Explanation:

SSE-C is used for decrypting objects.

Restrictions:

Only AES256 is supported.

Value range:

AES256

Default value:

None

SseCKey

string

Yes when SSE-C is used

Explanation:

Key used for decrypting objects when SSE-C is used

Restrictions:

A Base64-encoded, 256-bit value, for example, K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

Value range:

None

Default value:

None
  • If a download request includes IfUnmodifiedSince or IfMatch but does not meet the conditions specified by these parameters, an exception is thrown with HTTP status code 412 Precondition Failed.
  • If a download request includes IfModifiedSince or IfNoneMatch but does not meet the conditions specified by these parameters, an exception is thrown with HTTP status code 304 Not Modified.

Responses

Table 2 Responses

Type

Description

Table 3

NOTE:

This API returns a Promise response, which requires the Promise or async/await syntax.

Explanation:

Returned results. For details, see Table 3.
Table 3 Response

Parameter

Type

Description

CommonMsg

ICommonMsg

Explanation:

Common information generated after an API call is complete, including the HTTP status code and error code. For details, see Table 4.

InterfaceResult

Table 5

Explanation:

Results outputted for a successful call. For details, see Table 5.

Restrictions:

This parameter is not included if the value of Status is greater than 300.
Table 4 ICommonMsg

Parameter

Type

Description

Status

number

Explanation:

HTTP status code returned by the OBS server.

Value range:

A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors). For details, see Status Codes.

Code

string

Explanation:

Error code returned by the OBS server.

Message

string

Explanation:

Error description returned by the OBS server.

HostId

string

Explanation:

Request server ID returned by the OBS server.

RequestId

string

Explanation:

Request ID returned by the OBS server.

Id2

string

Explanation:

Request ID2 returned by the OBS server.

Indicator

string

Explanation:

Error code details returned by the OBS server.
Table 5 DownloadFileOutput

Parameter

Type

Description

RequestId

string

Explanation:

Request ID returned by the OBS server

DeleteMarker

string

Explanation:

Whether the deleted object is a delete marker.

LastModified

string

Explanation:

Time when the object was last modified.

CacheControl

string

Explanation:

Cache-Control header in the response

ContentDisposition

string

Explanation:

Content-Disposition header in the response

ContentEncoding

string

Explanation:

Content-Encoding header in the response

ContentLanguage

string

Explanation:

Content-Language header in the response

ContentType

string

Explanation:

MIME type of the object

Expires

string

Explanation:

Expires header in the response

ETag

string

Explanation:

ETag of the object

VersionId

string

Explanation:

Object version ID

WebsiteRedirectLocation

string

Explanation:

Location where an object is redirected. It is available when website hosting is configured for a bucket.

StorageClass

string

Explanation:

Object storage class. If the storage class is Standard, this parameter is left blank.

Restore

string

Explanation:

Restoration status of the object in the Archive storage class

Expiration

string

Explanation:

Expiration details

Metadata

object

Explanation:

Custom metadata of the object. You need to add in the CORS configurations the additional headers allowed to be carried in the response. For example, you can add the x-amz-meta-property1 header to allow custom metadata property1 to be returned.

SseKms

string

Explanation:

SSE-KMS is used for encrypting objects on the server side.

SseKmsKey

string

Explanation:

ID of the KMS master key when SSE-KMS is used.

SseC

string

Explanation:

SSE-C is used for encrypting objects on the server side.

SseCKeyMd5

string

Explanation:

MD5 value of the key used for encrypting objects when SSE-C is used. This value is used to check whether any error occurs during the transmission of the key.

Restrictions:

Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

Code Examples

This example downloads example/objectname from examplebucket using resumable download.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
// Import the OBS library.
// Use npm to install the client.
const ObsClient = require("esdk-obs-nodejs");
// Use the source code to install the client.
// var ObsClient = require('./lib/obs');

// Create an instance of ObsClient.
const obsClient = new ObsClient({
  // Obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways. Using hard coding may result in leakage.
  // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
  access_key_id: process.env.ACCESS_KEY_ID,
  secret_access_key: process.env.SECRET_ACCESS_KEY,
  // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
  // security_token: process.env.SECURITY_TOKEN,
  // Enter the endpoint corresponding to the region where the bucket is located. CN-Hong Kong is used here in this example. Replace it with the one currently in use.
  server: "https://obs.ap-southeast-1.myhuaweicloud.com"
});

async function downloadFile() {
  try {
    const params = {
      // Specify the bucket name.
      Bucket: 'examplebucket',
      // Specify the object (example/objectname in this example).
      Key: 'example/objectname',
      // Specify a local absolute path (/tmp/objectname in this example) for download. If the path is left blank, the current working directory is used by default.
      DownloadFile: 'localfile',
      // Specify whether to enable resumable transmission. Value true is used in this example. The default value is false.
      EnableCheckpoint: true,
      // Specify a part size, in bytes. This example sets each part to 9 MB.
      PartSize: 9 * 1024 * 1024,
      // Specify the maximum number of parts that can be concurrently transmitted. 5 is used in this example.
      TaskNum: 5
    };
    // Download the object using resumable download.
    const result = await obsClient.downloadFile(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Download file(%s) under the bucket(%s) successful!", params.Key, params.Bucket);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      console.log("StorageClass:%s, ETag:%s, ContentType:%s, ContentLength:%d, LastModified:%s",
        result.InterfaceResult.StorageClass, result.InterfaceResult.ETag, result.InterfaceResult.ContentType,
        result.InterfaceResult.ContentLength, result.InterfaceResult.LastModified,
      );
      return;
    };
    console.log("An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    console.log("Status: %d", result.CommonMsg.Status);
    console.log("Code: %s", result.CommonMsg.Code);
    console.log("Message: %s", result.CommonMsg.Message);
    console.log("RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    console.log("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.");
    console.log(error);
  };
};

downloadFile();