tencent cloud

文档反馈

下载对象

最后更新时间:2024-01-05 14:14:08

    简介

    本文档提供关于下载对象的 API 概览以及 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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    .Build();
    
    string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.tencentcloud.com/cam/capi
    string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.tencentcloud.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.tencentcloud.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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    .Build();
    
    string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.tencentcloud.com/cam/capi
    string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.tencentcloud.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.tencentcloud.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 查看。

    示例代码六: 下载暂停、继续与取消

    对于下载任务,可以通过以下方式暂停:
    downloadTask.Pause();
    暂停之后,可以通过以下方式续传:
    downloadTask.Resume();
    也通过以下方式取消上传:
    downloadTask.Cancel();
    说明
    更多完整示例,请前往 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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    .Build();
    
    string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.tencentcloud.com/cam/capi
    string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.tencentcloud.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.tencentcloud.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://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    .Build();
    
    string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.tencentcloud.com/cam/capi
    string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.tencentcloud.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.tencentcloud.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 查看。
    联系我们

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

    技术支持

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

    7x24 电话支持