Downloading Objects

Last updated: 2023-09-13 11:35:01

Feature Overview

Note
This API is used to read the object content. If you need to launch a browser to download the file, you can get the URL through cos.getObjectUrl and then start a download in the browser. For more information, see Pre-signed URL.
This document provides an overview of APIs and SDK code samples for downloading an object.
API
Operation
Description
Downloading object
Downloads an object to the local file system

Simple Operations

Downloading a single object

Note

This API (GET Object) is used to download an object in a COS bucket to a local file system. To call this API, you need to have permission to read the object, or the object is set to public-read.

Use Cases

cos.getObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
}, function (err, data) {
console.log(err || data.Body);
});
Get the file content with Range specified:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Range: 'bytes=1-3', /* Optional */
}, function (err, data) {
console.log(err || data.Body);
});
Download the file to a specified path:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Output: './exampleobject',
}, function (err, data) {
console.log(err || data);
});
Download the file to a specified write file stream:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Output: fs.createWriteStream('./exampleobject'),
}, function (err, data) {
console.log(err || data);
});
Downloading an object (limiting single-URL speed):
Note
For more information about the speed limits on object downloads, see Single-Connection Bandwidth Limit.
cos.getObject({
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
Key: '1.jpg', /* The object key stored in the bucket (e.g., 1.jpg, a/b/test.txt), required field */
Headers: {
'x-cos-traffic-limit': 819200, // The valid range for the limit value is 819,200 - 838,860,800, with the default unit being bit/s, i.e., 800Kb/s - 800Mb/s. If it exceeds this range, a 400 error will be returned.
},
}, function (err, data) {
console.log(err || data.Body);
});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
Output
An output file path or a write stream. If this parameter is specified, the full content will be written to data in the callback function.
String/WriteStream
Not required
ResponseContentType
Sets the Content-Type parameter in the response header.
String
Not required
ResponseContentLanguage
Sets the Content-Language parameter in the response header.
String
Not required
ResponseExpires
Sets the Content-Expires parameter in the response header.
String
Not required
ResponseCacheControl
Sets the Cache-Control parameter in the response header.
String
Not required
ResponseContentDisposition
Sets the Content-Disposition parameter in the response header.
String
Not required
ResponseContentEncoding
Sets the Content-Encoding parameter in the response header.
String
Not required
Range
Byte range of the object as defined in RFC 2616. The range value must be in the format of bytes=first-last, where both first and last are offsets starting from 0. For example, bytes=0-9 means that you want to copy the first 10 bytes of data of the source object. If this parameter is not specified, the entire object will be downloaded.
String
Not required
IfModifiedSince
If the object is modified after the specified time, the corresponding object metadata will be returned; otherwise, "304 (not modified)" will be returned.
String
Not required
IfUnmodifiedSince
If the object is not modified after the specified time, the object will be returned; otherwise, HTTP status 412 (precondition failed) will be returned
String
Not required
IfMatch
The object will be returned only if the value of ETag matches the specified content; otherwise, "412 (precondition failed)" will be returned.
String
Not required
IfNoneMatch
The file will be returned only if the value of ETag does not match the specified content; otherwise, "304 (not modified)" will be returned.
String
Not required
VersionId
Version ID of the object to download
String
Not required
onProgress
Progress callback function. Attributes of the progress callback response object, progressData, are as follows
Function
Not required
- progressData.loaded
Size of the downloaded parts, in bytes
Number
Not required
- progressData.total
Size of the entire object, in bytes
Number
Not required
- progressData.speed
Download speed, in bytes/s
Number
Not required
- progressData.percent
Percentage of the file download progress, in decimal form. For example, 0.5 means 50% has been downloaded.
Number
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
err
Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object returned when the request is successful. If the request fails, this parameter is empty.
Object
- statusCode
HTTP status code returned by the request, such as 200, 304, 403, and 404
Number
- headers
Returned headers
Object
- CacheControl
Cache directives as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
String
- ContentDisposition
Filename as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
String
- ContentEncoding
Encoding format as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
String
- Expires
Cache expiration time as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
String
- x-cos-storage-class
Object storage class, enumeration values: STANDARD, STANDARD_IA, ARCHIVE.
Note: If this header is not returned, it indicates that the file storage class is STANDARD (standard storage).
String
- x-cos-meta-*
User defined metadata
String
- NotModified
This attribute will be returned if the request contains IfModifiedSince. If the file has been modified, false will be returned. If not, true will be returned.
Boolean
- ETag
Returns the MD5 checksum value of the file. The ETag value can be used to verify whether the object has been damaged during the upload or download process.
For example, "09cba091df696af91549de27b8e7d0f6", Note: The ETag value here is enclosed in double quotes
String
- VersionId
Version ID of the object to download
String
- Body
Content of the returned file. The default form is buffer.
Buffer

Downloading multiple objects

Use Cases

Downloading multiple objects with a specified prefix (downloading files in a specified directory):
var config = {
Bucket: 'examplebucket-1250000000', /* Enter your own bucket, required field */
Region: 'COS_REGION', /* Required field specifying the region where the bucket is located, e.g., ap-beijing */
}

// Example of how to create a directory recursively. You can implement it by yourself.
function mkdirsSync(dirname) {
if(fs.existsSync(dirname)) {
return true;
} else {
if(mkdirsSync(path.dirname(dirname))) {
fs.mkdirSync(dirname);
return true;
}
}
}

// Download a single object
function downloadItem(Key, downloadPath) {
cos.getObject({
Bucket: config.Bucket,
Region: config.Region,
Key: Key,
Output: fs.createWriteStream(downloadPath),
},
function(err, data) {
console.log(err || data);
});
}

// Download multiple objects
function batchDownload(marker = undefined) {
cos.getBucket({
Bucket: config.Bucket,
Region: config.Region,
Prefix: '1', // Query all files with a prefix of 1
Marker: marker,
MaxKeys: 1000,
},
function (listError, listResult) {
if (listError) return console.log(listError);
// Download to the 'download' directory in the current directory
var localPath = 'download';
listResult.Contents.forEach(function (item) {
var downloadPath = path.resolve(localPath, item.Key);
var pathParse = path.parse(item.Key);
if (pathParse.dir) {
// If the object to be downloaded is in multiple directories, create the corresponding local directories
// For example, if the Key is a/b/1.png, create a local directory structure like a/b.
var mkdir = path.resolve(localPath, pathParse.dir);
mkdirsSync(mkdir);
downloadItem(item.Key, downloadPath);
} else {
downloadItem(item.Key, downloadPath);
}
});
})
}
batchDownload();

Advanced Operations (Recommended)

Multipart download

Note

Chunked download API, supporting concurrent chunked downloads. (Requires SDK version at least v2.9.14)

Method prototype

Multipart download sample:
var Key = 'test.zip';
cos.downloadFile({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Key: Key,
FilePath: './' + Key, // Local save path
ChunkSize: 1024 * 1024 * 8, // Chunk size
ParallelLimit: 5, // Concurrent number of chunks
RetryTimes: 3, // Number of retries for failed chunk uploads
TaskId: '123', // You can generate your own TaskId for canceling the download
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
},
}, function (err, data) {
console.log(err || data);
});

// Cancel the download task.
// cos.emit('inner-kill-task', {TaskId: '123'});

Description

Parameter
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID.
String
Required
Region
Bucket region. For the enumerated values, see Regions and Access Endpoints.
String
Required
Key
Object key (object name), the unique identifier of an object in a bucket. For more information, see Object Overview.
String
Required
FilePath
A path to store the downloaded file
String
Required
ChunkSize
Part size
Number
Not required
ParallelLimit
Number of parts to download concurrently
Number
Not required
RetryTimes
Number of retries for multipart download failures
Number
Not required
onProgress
Download Progress
String
Not required
- progressData.loaded
Size of the downloaded parts in bytes
Number
Not required
- progressData.total
Total file size in bytes
Number
Not required
- progressData.speed
File download speed in bytes/s
Number
Not required
- progressData.percent
File download percentage, represented as a decimal, for example: 50% downloaded is represented as 0.5.
Number
Not required

Callback function description

function(err, data) { ... }
Parameter
ParameterDescription
Local Disk Types
err
Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, see Error Codes.
Object
- statusCode
HTTP status code, such as 200, 403, and 404
Number
- headers
Returned headers
Object
data
Object returned when the request is successful. If the request fails, this parameter is empty.
Object
- statusCode
HTTP status code returned by the request, such as 200, 304, 403, and 404
Number
- headers
Returned headers
Object
- CacheControl
Cache directives as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
String
- ContentDisposition
Filename as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
String
- ContentEncoding
Encoding format as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
String
- Expires
Cache expiration time as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
String
- x-cos-storage-class
Object storage class, enumeration values: STANDARD, STANDARD_IA, ARCHIVE.
Note: If this header is not returned, it indicates that the file storage class is STANDARD (standard storage).
String
- x-cos-meta-*
User defined metadata
String
- NotModified
This attribute will be returned if the request contains IfModifiedSince. If the file has been modified, false will be returned. If not, true will be returned.
Boolean
- ETag
Returns the MD5 checksum value of the file. The ETag value can be used to verify whether the object has been damaged during the upload or download process.
For example, "09cba091df696af91549de27b8e7d0f6", Note: The ETag value here is enclosed in double quotes
String
- VersionId
Version ID of the object to download
String