控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

有奖征文|投稿上云技术实践,赢取价值5000元大奖> HOT

简介

本文档提供关于下载对象的 API 概览以及 SDK 示例代码。

API 操作名 操作描述
GET Object 下载对象 下载一个对象至本地

SDK API 参考

SDK 所有接口的具体参数与方法说明,请参考 SDK API

高级接口(推荐)

下载对象(断点续传)

高级接口支持暂停、恢复以及取消下载请求,同时支持断点下载功能。

说明:

  • .NET Framework 4.0 及以下的用户,高级接口暂不可用,详见 向下兼容指南
  • 高级下载接口从 5.4.26 版本开始支持并发分块下载,下载新版 SDK 前往 Releases 或参见 快速入门

示例代码一: 下载对象

using COSXML.Model.Object;
using COSXML.Auth;
using COSXML.Transfer;
using System;
using COSXML;
using System.Threading.Tasks;

namespace COSSnippet
{
    public class TransferDownloadObjectModel {

      private CosXml cosXml;

      TransferDownloadObjectModel() {
        CosXmlConfig config = new CosXmlConfig.Builder()
          .SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://cloud.tencent.com/document/product/436/6224
          .Build();

        string secretId = "SECRET_ID";   // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        long durationSecond = 600;          //每次请求签名有效时长,单位为秒
        QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
          secretKey, durationSecond);

        this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
      }

      /// 高级接口下载对象
      public async Task TransferDownloadObject()
      {
        // 初始化 TransferConfig
        TransferConfig transferConfig = new TransferConfig();
        // 手动设置高级下载接口的分块阈值为 20MB(默认为20MB), 从5.4.26版本开始支持!
        //transferConfig.DivisionForDownload = 20 * 1024 * 1024;
        // 手动设置高级下载接口的分块大小为 10MB(默认为5MB),不建议此处设置过小的分块值,可能导致频繁重试或下载速度不合预期
        //transferConfig.SliceSizeForDownload = 10 * 1024 * 1024;

        // 初始化 TransferManager
        TransferManager transferManager = new TransferManager(cosXml, transferConfig);

        String bucket = "examplebucket-1250000000"; //存储桶,格式:BucketName-APPID
        String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键
        string localDir = System.IO.Path.GetTempPath();//本地文件夹
        string localFileName = "my-local-temp-file"; //指定本地保存的文件名

        // 下载对象
        COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(bucket, cosPath, 
          localDir, localFileName);

        // 手动设置高级下载接口的并发数 (默认为5), 从5.4.26版本开始支持!
        //downloadTask.SetMaxTasks(10);
        downloadTask.progressCallback = delegate (long completed, long total)
        {
            Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
        };

        try {
          COSXML.Transfer.COSXMLDownloadTask.DownloadTaskResult result = await 
            transferManager.DownloadAsync(downloadTask);
          Console.WriteLine(result.GetResultInfo());
          string eTag = result.eTag;
        }
        catch (COSXML.CosException.CosClientException clientEx)
        {
          //请求失败
          Console.WriteLine("CosClientException: " + clientEx);
        }
        catch (COSXML.CosException.CosServerException serverEx)
        {
          //请求失败
          Console.WriteLine("CosServerException: " + serverEx.GetInfo());
        }
      }


      static void Main(string[] args)
      {
        TransferDownloadObjectModel m = new TransferDownloadObjectModel();

        /// 高级接口下载对象
        m.TransferDownloadObject().Wait();
      }
    }
}

说明:

更多完整示例,请前往 GitHub 查看。

示例代码二: 设置下载支持断点续传

COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(request);
 //开启断点续传,当本地存在未下载完成文件时,追加下载到文件末尾
 //本地文件已存在部分不符合本次下载的内容,可能导致下载失败,请删除文件重试
 downloadTask.SetResumableDownload(true);
 try {
   COSXML.Transfer.COSXMLDownloadTask.DownloadTaskResult result = await 
   transferManager.DownloadAsync(downloadTask);
   Console.WriteLine(result.GetResultInfo());
   string eTag = result.eTag;
 } catch (Exception e) {
   Console.WriteLine("CosException: " + e);
 }

说明:

更多完整示例,请前往 GitHub 查看。

示例代码三: 批量下载

TransferConfig transferConfig = new TransferConfig();

// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);

// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string localDir = System.IO.Path.GetTempPath();//本地文件夹

for (int i = 0; i < 5; i++) {
  // 下载对象
  string cosPath = "exampleobject" + i; //对象在存储桶中的位置标识符,即称对象键
  string localFileName = "my-local-temp-file"; //指定本地保存的文件名
  COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(bucket, cosPath, 
    localDir, localFileName);
  await transferManager.DownloadAsync(downloadTask);
}

说明:

更多完整示例,请前往 GitHub 查看。

示例代码四:单链接限速下载

TransferConfig transferConfig = new TransferConfig();

// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);

String bucket = "examplebucket-1250000000"; //存储桶,格式:BucketName-APPID
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键
string localDir = System.IO.Path.GetTempPath();//本地文件夹
string localFileName = "my-local-temp-file"; //指定本地保存的文件名

GetObjectRequest request = new GetObjectRequest(bucket, 
        cosPath, localDir, localFileName);
request.LimitTraffic(8 * 1000 * 1024); // 限制为1MB/s

COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(request);
await transferManager.DownloadAsync(downloadTask);

说明:

更多完整示例,请前往 GitHub 查看。

示例代码五:文件夹下载

using COSXML.Common;
using COSXML.CosException;
using COSXML.Model;
using COSXML.Model.Object;
using COSXML.Model.Tag;
using COSXML.Model.Bucket;
using COSXML.Model.Service;
using COSXML.Utils;
using COSXML.Auth;
using COSXML.Transfer;
using System;
using COSXML;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Text;
using System.Threading;
using System.Threading.Tasks;

namespace COSSnippet
{
  public class TransferDownloadObjectModel {

    private CosXml cosXml;
    private string nextMarker;

    TransferDownloadObjectModel() {
      CosXmlConfig config = new CosXmlConfig.Builder()
        .SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://cloud.tencent.com/document/product/436/6224
        .Build();

      string secretId = "SECRET_ID";   // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
      string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
      long durationSecond = 600; //每次请求签名有效时长,单位为秒
      QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
        secretKey, durationSecond);

      this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
  }

    public void GetObjectsFromFolder()
    {
    // 注意:COS中实际不存在文件夹下载的接口
    // 需要通过组合 “指定前缀列出” 和 “遍历列出的对象key做下载” 两种操作,实现类似文件夹下载的操作
    // 下面的操作,把对象列出到列表里,然后异步下载列表中的对象
        String nextMarker = null;

        List<string>  downloadList = new List<string>();
        string bucket = "examplebucket-1250000000";
        string prefix = "folder1/"; //指定前缀
        // 循环请求直到没有下一页数据
        do
        {
            // 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.cloud.tencent.com/developer
            GetBucketRequest listRequest = new GetBucketRequest(bucket);
            //获取 folder1/ 下的所有对象以及子目录
            listRequest.SetPrefix(prefix);
            listRequest.SetMarker(nextMarker);
            //执行列出对象请求
            GetBucketResult listResult = cosXml.GetBucket(listRequest);
            ListBucket info = listResult.listBucket;
            // 对象列表
            List<ListBucket.Contents> objects = info.contentsList;
            // 下一页的下标
            nextMarker = info.nextMarker;

            //对象列表
            foreach (var content in objects)
            {
            downloadList.Add(content.key);
            Console.WriteLine("adding key:" + content.key);
            }
      } while (nextMarker != null);
        Console.WriteLine("download list construct done, " + downloadList.Count + " objects added");

        TransferConfig transferConfig = new TransferConfig();
        TransferManager transferManager = new TransferManager(cosXml, transferConfig);
        string localDir = System.IO.Path.GetTempPath();//本地文件夹

        List<Task> taskList = new List<Task>();
        for (int i = 0; i < downloadList.Count; i++)
        {
            // 遍历待下载列表,下载内容写到 filename_i 文件中
            COSXMLDownloadTask downloadTask = new COSXMLDownloadTask(bucket, downloadList[i], 
                localDir, "filename_" + i.ToString());
            // 异步下载, 加入task队列
            Task task = transferManager.DownloadAsync(downloadTask);
            taskList.Add(task); 
        }
        Console.WriteLine("download tasks submitted, total " + taskList.Count + " tasks added");

        //等待TaskList中所有Task结束
        foreach(Task task in taskList)
        {
            task.Wait();
            Console.WriteLine("download completed");
        }
  }

      static void Main(string[] args)
      {
        TransferDownloadObjectModel m = new TransferDownloadObjectModel();
        /// 批量下载文件夹中文件
        m.GetObjectsFromFolder();
      }
    }
}

说明:

更多完整示例,请前往 GitHub 查看。

简单操作

下载对象

功能说明

下载一个 Object(文件/对象)至本地(GET Object)。

示例代码一:单对象简单下载

using COSXML.Model.Object;
using COSXML.Auth;
using System;
using COSXML;

namespace COSSnippet
{
    public class GetObjectModel {

      private CosXml cosXml;

      GetObjectModel() {
        CosXmlConfig config = new CosXmlConfig.Builder()
          .SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://cloud.tencent.com/document/product/436/6224 
          .Build();

        string secretId = "SECRET_ID";   // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        long durationSecond = 600;          //每次请求签名有效时长,单位为秒
        QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
          secretKey, durationSecond);

        this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
      }

      /// 下载对象
      public void GetObject()
      {
        //.cssg-snippet-body-start:[get-object]
        try
        {
          // 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.cloud.tencent.com/developer
          string bucket = "examplebucket-1250000000";
          string key = "exampleobject"; //对象键
          string localDir = System.IO.Path.GetTempPath();//本地文件夹
          string localFileName = "my-local-temp-file"; //指定本地保存的文件名
          GetObjectRequest request = new GetObjectRequest(bucket, key, localDir, localFileName);
          //设置进度回调
          request.SetCosProgressCallback(delegate (long completed, long total)
          {
            Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
          });
          //执行请求
          GetObjectResult result = cosXml.GetObject(request);
          //请求成功
          Console.WriteLine(result.GetResultInfo());
        }
        catch (COSXML.CosException.CosClientException clientEx)
        {
          //请求失败
          Console.WriteLine("CosClientException: " + clientEx);
        }
        catch (COSXML.CosException.CosServerException serverEx)
        {
          //请求失败
          Console.WriteLine("CosServerException: " + serverEx.GetInfo());
        }
      }

      static void Main(string[] args)
      {
        GetObjectModel m = new GetObjectModel();
        /// 下载对象
        m.GetObject();
      }
    }
}

说明:

更多完整示例,请前往 GitHub 查看。

示例代码二:下载对象到内存中

using COSXML.Model.Object;
using COSXML.Auth;
using System;
using COSXML;

namespace COSSnippet
{
    public class GetObjectModel {

      private CosXml cosXml;

      GetObjectModel() {
        CosXmlConfig config = new CosXmlConfig.Builder()
          .SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://cloud.tencent.com/document/product/436/6224 
          .Build();

        string secretId = "SECRET_ID";   // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.cloud.tencent.com/cam/capi
        long durationSecond = 600;          //每次请求签名有效时长,单位为秒
        QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId, 
          secretKey, durationSecond);

        this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
      }

      /// 下载返回 bytes 数据
      public void downloadToMem() {
        try
        {
          // 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.cloud.tencent.com/developer
          string bucket = "examplebucket-1250000000";
          string key = "exampleobject"; //对象键

          GetObjectBytesRequest request = new GetObjectBytesRequest(bucket, key);
          //设置进度回调
          request.SetCosProgressCallback(delegate (long completed, long total)
          {
            Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
          });
          //执行请求
          GetObjectBytesResult result = cosXml.GetObject(request);
          //获取内容到 byte 数组中
          byte[] content = result.content;
          //请求成功
          Console.WriteLine(result.GetResultInfo());
        }
        catch (COSXML.CosException.CosClientException clientEx)
        {
          //请求失败
          Console.WriteLine("CosClientException: " + clientEx);
        }
        catch (COSXML.CosException.CosServerException serverEx)
        {
          //请求失败
          Console.WriteLine("CosServerException: " + serverEx.GetInfo());
        }
      }

      // .cssg-methods-pragma

      static void Main(string[] args)
      {
        GetObjectModel m = new GetObjectModel();

        /// 下载对象到内存中
        m.downloadToMem();
        // .cssg-methods-pragma
      }
    }
}

说明:

更多完整示例,请前往 GitHub 查看。

目录