有奖捉虫:云通信与企业服务文档专题,速来> HOT

简介

注意
该接口用于读取对象内容,如果需要发起浏览器下载文件,可以通过 cos.getObjectUrl 获取 url 再触发浏览器下载,具体参见 预签名 URL 文档。
本文档提供关于对象的下载操作相关的 API 概览以及 SDK 示例代码。
API
操作名
操作描述
下载对象
下载一个对象至本地

简单操作

下载单个对象

功能说明

GET Object 接口请求可以获取存储桶里指定对象的内容并下载至本地。该 API 的请求者需要对目标对象有读取权限,或者目标对象向所有人开放了读取权限(公有读)。

使用示例

cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
}, function(err, data) {
console.log(err || data.Body);
});
指定 Range 获取文件内容:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Range: 'bytes=1-3', /* 非必须 */
}, function(err, data) {
console.log(err || data.Body);
});
下载文件到指定路径:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Output: './exampleobject',
}, function(err, data) {
console.log(err || data);
});
下载文件到指定写文件流:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
console.log(err || data);
});
下载对象(单链接限速):
说明
关于下载对象的限速说明,请参见 单链接限速
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
Headers: {
'x-cos-traffic-limit': 819200, // 限速值设置范围为819200 - 838860800,单位默认为 bit/s,即800Kb/s - 800Mb/s,如果超出该范围将返回400错误。
},
}, function(err, data) {
console.log(err || data.Body);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
Output
输出的文件路径或者一个写流,若不传入,则将完整内容写入回调函数data
String/WriteStream
ResponseContentType
设置响应头部中的 Content-Type 参数
String
ResponseContentLanguage
设置返回头部中的 Content-Language 参数
String
ResponseExpires
设置返回头部中的 Content-Expires 参数
String
ResponseCacheControl
设置返回头部中的 Cache-Control 参数
String
ResponseContentDisposition
设置返回头部中的 Content-Disposition 参数
String
ResponseContentEncoding
设置返回头部中的 Content-Encoding 参数
String
Range
RFC 2616 中定义的字节范围,范围值必须使用 bytes=first-last 格式,first 和 last 都是基于0开始的偏移量。例如 bytes=0-9 表示下载对象的开头10个字节的数据 ,如果不指定,则表示下载整个对象
String
IfModifiedSince
当对象在指定时间后被修改,则返回对应对象的元数据信息,否则返回304(not modified)
String
IfUnmodifiedSince
当对象在指定时间后未被修改,则返回对象,否则返回412(precondition failed)
String
IfMatch
当 ETag 与指定的内容一致,才返回对象,否则返回412(precondition failed)
String
IfNoneMatch
当 ETag 与指定的内容不一致,才返回对象,否则返回304(not modified)
String
VersionId
指定要下载的对象的版本 ID
String
onProgress
进度的回调函数,进度回调响应对象(progressData)属性如下
Function
- progressData.loaded
已经下载的对象部分大小,以字节(Bytes)为单位
Number
- progressData.total
整个对象的大小,以字节(Bytes)为单位
Number
- progressData.speed
对象的下载速度,以字节/秒(Bytes/s)为单位
Number
- progressData.percent
对象下载的百分比,以小数形式呈现,例如:下载50%即为0.5
Number

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200,304,403,404等
Number
- headers
请求返回的头部信息
Object
- CacheControl
RFC 2616 中定义的缓存指令,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- ContentDisposition
RFC 2616 中定义的文件名称,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- ContentEncoding
RFC 2616 中定义的编码格式,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- Expires
RFC 2616 中定义的缓存失效时间,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- x-cos-storage-class
对象的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE,
注意:如果没有返回该头部,则说明文件存储级别为 STANDARD (标准存储)
String
- x-cos-meta-*
用户自定义的元数据
String
- NotModified
如果请求时带有 IfModifiedSince 则返回该属性,如果文件未被修改,则为 true,否则为 false
Boolean
- ETag
返回文件的 MD5 算法校验值。ETag 的值可以用于检查对象在上传、下载过程中是否有损坏
例如"09cba091df696af91549de27b8e7d0f6"注意:这里的 ETag 值字符串前后带有双引号
String
- VersionId
指定要下载的对象的版本 ID
String
- Body
返回的文件内容,默认为 Buffer 形式
Buffer

批量下载对象

使用示例

按前缀下载多个对象(下载指定目录下的文件):
var config = {
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如ap-beijing,必须字段 */
}

// 递归创建目录举例,可自行实现
function mkdirsSync(dirname) {
if(fs.existsSync(dirname)) {
return true;
}else{
if(mkdirsSync(path.dirname(dirname))) {
fs.mkdirSync(dirname);
return true;
}
}
}

// 下载单个文件
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);
});
}

// 批量下载文件
function batchDownload(marker = undefined) {
cos.getBucket({
Bucket: config.Bucket,
Region: config.Region,
Prefix: '1', // 查询前缀是1的所有文件
Marker: marker,
MaxKeys: 1000,
},
function (listError, listResult) {
if (listError) return console.log(listError);
// 下载到本目录下的download目录下
var localPath = 'download';
listResult.Contents.forEach(function (item) {
var downloadPath = path.resolve(localPath, item.Key);
var pathParse = path.parse(item.Key);
if (pathParse.dir) {
// 如果被下载的对象在多层目录下,就在本地创建对应的目录
// 例如Key是a/b/1.png,就在本地创建a/b这样的目录结构
var mkdir = path.resolve(localPath, pathParse.dir);
mkdirsSync(mkdir);
downloadItem(item.Key, downloadPath);
} else {
downloadItem(item.Key, downloadPath);
}
});
})
}
batchDownload();

高级操作(推荐)

分块下载对象

功能说明

分块下载接口,支持分块并发下载。(要求sdk版本至少在v2.9.14)

方法原型

分块下载示例:
var Key = 'test.zip';
cos.downloadFile({
Bucket: 'examplebucket-1250000000',
Region: 'ap-beijing',
Key: Key,
FilePath: './' + Key, // 本地保存路径
ChunkSize: 1024 * 1024 * 8, // 分块大小
ParallelLimit: 5, // 分块并发数
RetryTimes: 3, // 分块失败重试次数
TaskId: '123', // 可以自己生成TaskId,用于取消下载
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
},
}, function (err, data) {
console.log(err || data);
});

// 取消下载任务
// cos.emit('inner-kill-task', {TaskId: '123'});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
FilePath
下载文件是保存的路径
String
ChunkSize
下载时的分块大小
Number
ParallelLimit
分块并发数
Number
RetryTimes
分块下载失败重试次数
Number
onProgress
下载进度
String
- progressData.loaded
已经下载的文件部分大小,以字节(Bytes)为单位
Number
- progressData.total
整个文件的大小,以字节(Bytes)为单位
Number
- progressData.speed
文件的下载速度,以字节/秒(Bytes/s)为单位
Number
- progressData.percent
文件的下载百分比,以小数形式呈现,例如:下载50%即为0.5
Number

回调函数说明

function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码,例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象,如果请求发生错误,则为空
Object
- statusCode
请求返回的 HTTP 状态码,例如200,304,403,404等
Number
- headers
请求返回的头部信息
Object
- CacheControl
RFC 2616 中定义的缓存指令,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- ContentDisposition
RFC 2616 中定义的文件名称,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- ContentEncoding
RFC 2616 中定义的编码格式,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- Expires
RFC 2616 中定义的缓存失效时间,仅当对象元数据包含此项或通过请求参数指定了此项时才会返回该头部
String
- x-cos-storage-class
对象的存储级别,枚举值:STANDARD、STANDARD_IA、ARCHIVE,
注意:如果没有返回该头部,则说明文件存储级别为 STANDARD (标准存储)
String
- x-cos-meta-*
用户自定义的元数据
String
- NotModified
如果请求时带有 IfModifiedSince 则返回该属性,如果文件未被修改,则为 true,否则为 false
Boolean
- ETag
返回文件的 MD5 算法校验值。ETag 的值可以用于检查对象在上传、下载过程中是否有损坏
例如"09cba091df696af91549de27b8e7d0f6"注意:这里的 ETag 值字符串前后带有双引号
String
- VersionId
指定要下载的对象的版本 ID
String