本文档提供关于上传对象的 API 概览以及 SDK 示例代码。
简单操作
API | 操作名 | 操作描述 |
---|---|---|
PUT Object | 简单上传对象 | 上传一个对象至存储桶 |
POST Object | 表单上传对象 | 使用表单请求上传对象 |
APPEND Object | 追加上传对象 | 使用分块追加的方式上传对象 |
分块操作
API | 操作名 | 操作描述 |
---|---|---|
List Multipart Uploads | 查询分块上传 | 查询正在进行中的分块上传信息 |
Initiate Multipart Upload | 初始化分块上传 | 初始化分块上传操作 |
Upload Part | 上传分块 | 分块上传对象 |
List Parts | 查询已上传块 | 查询特定分块上传操作中的已上传的块 |
Complete Multipart Upload | 完成分块上传 | 完成整个文件的分块上传 |
Abort Multipart Upload | 终止分块上传 | 终止一个分块上传操作并删除已上传的块 |
SDK 所有接口的具体参数与方法说明,请参考 SDK API。
高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持续传功能。
说明:
- 文件大小小于分块阈值时选择简单上传,超过阈值时使用分块上传,阈值支持用户自行配置,默认为5MB。
- 分块大小支持用户自行配置,默认为1MB。
- 针对.NET Framework 4.0 及以下的用户,高级接口暂不可用,详见 向下兼容指南。
using COSXML.Model.Object;
using COSXML.Auth;
using COSXML.Transfer;
using System;
using COSXML;
using System.Threading.Tasks;
namespace COSSnippet
{
public class TransferUploadObjectModel {
private CosXml cosXml;
TransferUploadObjectModel() {
CosXmlConfig config = new CosXmlConfig.Builder()
.SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://intl.cloud.tencent.com/document/product/436/6224
.Build();
string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
long durationSecond = 600; //每次请求签名有效时长,单位为秒
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
/// 高级接口上传文件
public async Task TransferUploadFile()
{
// 初始化 TransferConfig
TransferConfig transferConfig = new TransferConfig();
// 手动设置开始分块上传的大小阈值为10MB,默认值为5MB
transferConfig.DivisionForUpload = 10 * 1024 * 1024;
// 手动设置分块上传中每个分块的大小为2MB,默认值为1MB
transferConfig.SliceSizeForUpload = 2 * 1024 * 1024;
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
String bucket = "examplebucket-1250000000";
String cosPath = "exampleobject"; //对象在存储桶中的位置标识符,即称对象键
String srcPath = @"temp-source-file";//本地文件绝对路径
// 上传对象
COSXMLUploadTask uploadTask = new COSXMLUploadTask(bucket, cosPath);
uploadTask.SetSrcPath(srcPath);
uploadTask.progressCallback = delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
};
try {
COSXML.Transfer.COSXMLUploadTask.UploadTaskResult result = await
transferManager.UploadAsync(uploadTask);
Console.WriteLine(result.GetResultInfo());
string eTag = result.eTag;
} catch (Exception e) {
Console.WriteLine("CosException: " + e);
}
}
static void Main(string[] args)
{
TransferUploadObjectModel m = new TransferUploadObjectModel();
/// 高级接口上传对象
m.TransferUploadFile().Wait();
// .cssg-methods-pragma
}
}
}
说明:
using COSXML.Model.Object;
using COSXML.Auth;
using COSXML.Transfer;
using System;
using COSXML;
namespace COSSnippet
{
public class TransferUploadObjectModel {
private CosXml cosXml;
TransferUploadObjectModel() {
CosXmlConfig config = new CosXmlConfig.Builder()
.SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://intl.cloud.tencent.com/document/product/436/6224
.Build();
string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
long durationSecond = 600; //每次请求签名有效时长,单位为秒
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
/// 上传二进制数据
public void TransferUploadBytes()
{
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string cosPath = "exampleObject"; // 对象键
byte[] data = new byte[1024]; // 二进制数据
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, data);
// 发起上传
PutObjectResult result = cosXml.PutObject(putObjectRequest);
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)
{
TransferUploadObjectModel m = new TransferUploadObjectModel();
/// 高级接口上传二进制数据
m.TransferUploadBytes();
}
}
}
说明:
using COSXML.Model.Object;
using COSXML.Utils;
using COSXML.Auth;
using System;
using COSXML;
using System.IO;
namespace COSSnippet
{
public class PutObjectModel {
private CosXml cosXml;
PutObjectModel() {
CosXmlConfig config = new CosXmlConfig.Builder()
.SetRegion("COS_REGION") // 设置默认的地域, COS 地域的简称请参照 https://intl.cloud.tencent.com/document/product/436/6224
.Build();
string secretId = "SECRET_ID"; // 云 API 密钥 SecretId, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
string secretKey = "SECRET_KEY"; // 云 API 密钥 SecretKey, 获取 API 密钥请参照 https://console.intl.cloud.tencent.com/cam/capi
long durationSecond = 600; //每次请求签名有效时长,单位为秒
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
/// 文件流上传, 从 5.4.24 版本开始支持
public void PutObjectStream()
{
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string srcPath = @"temp-source-file";//本地文件绝对路径
// 打开只读的文件流对象
FileStream fileStream = new FileStream(srcPath, FileMode.Open, FileAccess.Read);
// 组装上传请求,其中 offset sendLength 为可选参数
long offset = 0L;
long sendLength = fileStream.Length;
PutObjectRequest request = new PutObjectRequest(bucket, key, fileStream, offset, sendLength);
//设置进度回调
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
//执行请求
PutObjectResult result = cosXml.PutObject(request);
//关闭文件流
fileStream.Close();
//对象的 eTag
string eTag = result.eTag;
//对象的 crc64ecma 校验值
string crc64ecma = result.crc64ecma;
//打印请求结果
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)
{
PutObjectModel m = new PutObjectModel();
/// 从文件流上传对象
m.PutObjectStream();
}
}
}
说明:
对于上传任务,可以通过以下方式暂停:
uploadTask.Pause();
暂停之后,可以通过以下方式续传:
uploadTask.Resume();
也通过以下方式取消上传:
uploadTask.Cancel();
说明:更多完整示例,请前往 GitHub 查看。
TransferConfig transferConfig = new TransferConfig();
// 初始化 TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
for (int i = 0; i < 5; i++) {
// 上传对象
string cosPath = "exampleobject" + i; //对象在存储桶中的位置标识符,即称对象键
string srcPath = @"temp-source-file";//本地文件绝对路径
COSXMLUploadTask uploadTask = new COSXMLUploadTask(bucket, cosPath);
uploadTask.SetSrcPath(srcPath);
await transferManager.UploadAsync(uploadTask);
}
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string cosPath = "dir/"; // 对象键
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, new byte[0]);
cosXml.PutObject(putObjectRequest);
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:
PUT Object 接口可以上传一个对象至指定存储桶中,该操作需要请求者对存储桶有 WRITE 权限。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传 或 高级接口 上传。
注意:
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string srcPath = @"temp-source-file";//本地文件绝对路径
PutObjectRequest request = new PutObjectRequest(bucket, key, srcPath);
//设置进度回调
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
//执行请求
PutObjectResult result = cosXml.PutObject(request);
//对象的 eTag
string eTag = result.eTag;
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:
使用表单请求上传对象。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string srcPath = @"temp-source-file";//本地文件绝对路径
PostObjectRequest request = new PostObjectRequest(bucket, key, srcPath);
//设置进度回调
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
//执行请求
PostObjectResult result = cosXml.PostObject(request);
//请求成功
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
使用分块追加的方式上传对象。
说明:此功能从 5.4.22 版本开始支持,查看版本 Changelog 请前往 GitHub。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string srcPath = @"temp-source-file";//本地文件绝对路径
//首次append上传,追加位置传0,创建一个appendable对象
long next_append_position = 0;
AppendObjectRequest request = new AppendObjectRequest(bucket, key, srcPath, next_append_position);
//设置进度回调
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
AppendObjectResult result = cosXml.AppendObject(request);
//获取下次追加位置
next_append_position = result.nextAppendPosition;
Console.WriteLine(result.GetResultInfo());
//执行追加,传入上次获取的对象末尾
request = new AppendObjectRequest(bucket, key, srcPath, next_append_position);
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
result = cosXml.AppendObject(request);
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
这里说明下分块上传的流程。
查询指定存储桶中正在进行的分块上传(List Multipart Uploads)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
ListMultiUploadsRequest request = new ListMultiUploadsRequest(bucket);
//执行请求
ListMultiUploadsResult result = cosXml.ListMultiUploads(request);
//请求成功
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
初始化 Multipart Upload 上传操作,获取对应的 uploadId(Initiate Multipart Upload)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
InitMultipartUploadRequest request = new InitMultipartUploadRequest(bucket, key);
//执行请求
InitMultipartUploadResult result = cosXml.InitMultipartUpload(request);
//请求成功
this.uploadId = result.initMultipartUpload.uploadId; //用于后续分块上传的 uploadId
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
分块上传对象(Upload Part)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string uploadId = "exampleUploadId"; //初始化分块上传返回的uploadId
int partNumber = 1; //分块编号,必须从1开始递增
string srcPath = @"temp-source-file";//本地文件绝对路径
UploadPartRequest request = new UploadPartRequest(bucket, key, partNumber,
uploadId, srcPath, 0, -1);
//设置进度回调
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
//执行请求
UploadPartResult result = cosXml.UploadPart(request);
//请求成功
//获取返回分块的eTag,用于后续CompleteMultiUploads
this.eTag = result.eTag;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
查询特定分块上传操作中的已上传的块(List Parts)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string uploadId = "exampleUploadId"; //初始化分块上传返回的uploadId
ListPartsRequest request = new ListPartsRequest(bucket, key, uploadId);
//执行请求
ListPartsResult result = cosXml.ListParts(request);
//请求成功
//列举已上传的分块
List<COSXML.Model.Tag.ListParts.Part> alreadyUploadParts = result.listParts.parts;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
完成整个文件的分块上传(Complete Multipart Upload)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string uploadId = "exampleUploadId"; //初始化分块上传返回的uploadId
CompleteMultipartUploadRequest request = new CompleteMultipartUploadRequest(bucket,
key, uploadId);
//设置已上传的parts,必须有序,按照partNumber递增
request.SetPartNumberAndETag(1, this.eTag);
//执行请求
CompleteMultipartUploadResult result = cosXml.CompleteMultiUpload(request);
//请求成功
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。
try
{
// 存储桶名称,此处填入格式必须为 bucketname-APPID, 其中 APPID 获取参考 https://console.intl.cloud.tencent.com/developer
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; //对象键
string uploadId = "exampleUploadId"; //初始化分块上传返回的uploadId
AbortMultipartUploadRequest request = new AbortMultipartUploadRequest(bucket, key, uploadId);
//执行请求
AbortMultipartUploadResult result = cosXml.AbortMultiUpload(request);
//请求成功
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
//请求失败
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
//请求失败
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
说明:更多完整示例,请前往 GitHub 查看。
本页内容是否解决了您的问题?