tencent cloud

文档反馈

下载对象

最后更新时间:2024-01-19 16:15:11

    简介

    注意
    该接口用于读取对象内容,如果需要发起浏览器下载文件,可以通过 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,即100KB/s - 100MB/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();
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持