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 | 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 objectfunction 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 objectsfunction batchDownload(marker = undefined) {cos.getBucket({Bucket: config.Bucket,Region: config.Region,Prefix: '1', // Query all files with a prefix of 1Marker: marker,MaxKeys: 1000,},function (listError, listResult) {if (listError) return console.log(listError);// Download to the 'download' directory in the current directoryvar 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 pathChunkSize: 1024 * 1024 * 8, // Chunk sizeParallelLimit: 5, // Concurrent number of chunksRetryTimes: 3, // Number of retries for failed chunk uploadsTaskId: '123', // You can generate your own TaskId for canceling the downloadonProgress: 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 | 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 |