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

简介

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

功能说明

GET Object 接口请求可以获取存储桶里指定文件的内容,得到文件内容是字符串格式。 下载文件到本地请参见 预签名 URL

下载单个对象

使用示例

cos.getObject({
Bucket: 'examplebucket-1250000000', /* 填入您自己的存储桶,必须字段 */
Region: 'COS_REGION', /* 存储桶所在地域,例如 ap-beijing,必须字段 */
Key: '1.jpg', /* 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段 */
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
}
}, 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', /* 非必须 */
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data.Body);
});
返回blob格式文件内容:
cos.getObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
Key: 'exampleobject', /* 必须 */
DataType: 'blob', /* 非必须 */
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
}
}, 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),必须字段 */
Headers: {
'x-cos-traffic-limit': 819200, // 限速值设置范围为819200 - 838860800,单位默认为 bit/s,即800Kb/s - 800Mb/s,如果超出该范围将返回400错误。
},
onProgress: function (progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data.Body);
});

参数说明

参数名
参数描述
类型
是否必填
Bucket
存储桶的名称,命名格式为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
Key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
String
DataType
返回文件内容格式,枚举值:string、blob、arraybuffer,默认值:string
String
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,更多存储类型请参见 存储类型概述
注意:如果没有返回该头部,则说明文件存储类型为 STANDARD (标准存储)
String
- x-cos-meta-*
用户自定义的元数据
String
- NotModified
如果请求时带有 IfModifiedSince 则返回该属性,如果文件未被修改,则为 true,否则为 false
Boolean
- ETag
返回文件的 MD5 算法校验值。ETag 的值可以用于检查对象在上传、下载过程中是否有损坏
例如 "09cba091df696af91549de27b8e7d0f6"注意:这里的 ETag 值字符串前后带有双引号
String
- VersionId
指定要下载的对象的版本 ID
String
- Body
返回的文件内容,默认为 String 形式
String

批量下载对象

注意
不推荐使用,触发浏览器下载后,无法用代码控制开始、停止。当下载的对象过多时,可能造成较差的体验。

使用示例

按前缀下载多个对象(下载指定目录下的文件):
var getObjects = function (marker) {
cos.getBucket({
Bucket: config.Bucket,
Region: config.Region,
Prefix: 'abc', /* 要下载的目录,或要下载的前缀 */
Marker: marker,
MaxKeys: 1000,
}, function (listError, listResult) {
if (listError) return console.log('list error:', listError);
var nextMarker = listResult.NextMarker;
listResult.Contents.forEach(function (item) {
cos.getObjectUrl({
Bucket: config.Bucket,
Region: config.Region,
Key: item.Key,
}, function(err, data) {
if (err) return console.log(err);
setTimeout(() => {
var downloadUrl = data.Url + (data.Url.indexOf('?') > -1 ? '&' : '?') + 'response-content-disposition=attachment'; // 补充强制下载的参数
window.open(downloadUrl); // 这里是新窗口打开 url,如果需要在当前窗口打开,可以使用隐藏的 iframe 下载,或使用 a 标签 download 属性协助下载
}, 500);
});
});
// 如果没有处理完需要继续查询下一页文件列表
if (listResult.IsTruncated === 'true') getMultipleObjects(nextMarker);
});
}
getObjects();