tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
对象存储
    文档
    Download PDF

    下载对象

    最后更新时间：2024-01-22 11:23:32
    下载PDF

      简介

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

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

      联系我们
      技术支持

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

      提交工单
      7x24 电话支持
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款