Overview
This document provides an overview of APIs and SDK code samples related to object upload.
Simple operations
|
| | Uploads an object to a bucket. |
| Uploading an object using an HTML form | Uploads an object using an HTML form. |
| | Uploads an object by appending the object by parts. |
Multipart operations
|
| Querying multipart uploads | Queries in-progress multipart uploads. |
| Initializing a multipart upload operation | Initializes a multipart upload operation. |
| | Uploads an object in multiple parts. |
| | Queries the uploaded parts of a multipart upload. |
| Completing a multipart upload | Completes the multipart upload of a file. |
| Aborting a multipart upload | Aborts a multipart upload and deletes the uploaded parts. |
Advanced APIs (Recommended)
Uploading an object
Description
The advanced APIs encapsulate the simple upload and multipart upload APIs and can intelligently select the upload method based on file size. They also support checkpoint restart for resuming interrupted operations.
Note:
If the file size is less than the multipart upload threshold, simple upload is used. Otherwise, multiple upload is used. The multipart upload threshold is configurable and is 5 MB by default.
The part size is configurable and is 1 MB by default.
If your .NET Framework version is 4.0 or earlier, advanced APIs are not available. For more information, please see Backward Compatibility. Sample code 1. Uploading a local object via advanced API
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")
.Build();
string secretId = "SECRET_ID";
string secretKey = "SECRET_KEY";
long durationSecond = 600;
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
public async Task TransferUploadFile()
{
TransferConfig transferConfig = new TransferConfig();
transferConfig.DivisionForUpload = 10 * 1024 * 1024;
transferConfig.SliceSizeForUpload = 2 * 1024 * 1024;
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
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();
}
}
}
Note:
For the complete sample, go to GitHub. After the upload, you can generate a download URL for the uploaded file with the same key. For detailed directions, please see Generating Pre-signed Links. Please note that for private-read files, the download URL is only valid for a limited period of time. Sample code 2. Uploading binary data
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")
.Build();
string secretId = "SECRET_ID";
string secretKey = "SECRET_KEY";
long durationSecond = 600;
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
public void TransferUploadBytes()
{
try
{
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();
}
}
}
Note:
For the complete sample, go to GitHub. After the upload, you can generate a download URL for the uploaded file with the same key. For detailed directions, please see Generating Pre-signed Links. Please note that for private-read files, the download URL is only valid for a limited period of time. Sample code 3. Uploading with a file stream
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")
.Build();
string secretId = "SECRET_ID";
string secretKey = "SECRET_KEY";
long durationSecond = 600;
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);
this.cosXml = new CosXmlServer(config, qCloudCredentialProvider);
}
public void PutObjectStream()
{
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string srcPath = @"temp-source-file";
FileStream fileStream = new FileStream(srcPath, FileMode.Open, FileAccess.Read);
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();
string eTag = result.eTag;
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();
}
}
}
Note:
Uploading with a file stream is supported from v5.4.24. To download the latest version of SDK, go to Releases or refer to Getting Started. For the version changelog, see GitHub. For the complete sample, go to GitHub. After the upload, you can generate a download URL for the uploaded file with the same key. For detailed directions, please see Generating Pre-signed Links. Please note that for private-read files, the download URL is only valid for a limited period of time. Sample code 4. Suspending, resuming, and canceling an upload
To suspend an upload, use the code below:
To resume a suspended download, use the code below:
To cancel an upload, use the code below:
Note:
For the complete sample, go to GitHub. Sample code 5. Uploading multiple objects
TransferConfig transferConfig = new TransferConfig();
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
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);
}
Sample 6. Creating a directory
try
{
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());
}
Note:
For the complete sample, go to GitHub. After the upload, you can generate a download URL for the uploaded file with the same key. For detailed directions, please see Generating Pre-signed Links. Please note that for private-read files, the download URL is only valid for a limited period of time. Simple Operations
Uploading an object using simple upload
Description
This API (PUT Object) is used to upload an object smaller than 5 GB to a specified bucket. To call this API, you need to have permission to write to the bucket. If the object size is larger than 5 GB, please use Multipart Upload or Advanced APIs for the upload. Note:
The key (filename) cannot end with /; otherwise, it will be identified as a folder.
Each root account (APPID) can have up to 1,000 bucket ACLs and an unlimited number of object ACLs. Do not configure ACLs for an object during upload if you don’t need to control access to it. The object will inherit the permissions of its bucket by default.
Due to the limitations of the underlying SDK dependent language components, the general upload API may encounter unexpected exceptions in some environments when it is used to upload objects over 2 GB at a time. Therefore, we recommend you use the advanced API or multipart upload to avoid potential problems. Sample code
try
{
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);
string eTag = result.eTag;
}
catch (COSXML.CosException.CosClientException clientEx)
{
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub. After the upload, you can generate a download URL for the uploaded file with the same key. For detailed directions, please see Generating Pre-signed Links. Please note that for private-read files, the download URL is only valid for a limited period of time. Description
This API is used to upload an object using an HTML form.
Sample code
try
{
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());
}
Note:
For the complete sample, go to GitHub. Appending parts
Description
This API is used to upload an object by appending parts of the object.
Note:
This feature is supported starting from v5.4.22. For the version changelog, see GitHub. Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string srcPath = @"temp-source-file";
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());
}
Note:
For the complete sample, go to GitHub. Multipart Operations
The multipart upload process is outlined below.
1. Initialize the multipart upload with Initiate Multipart Upload and get the UploadId.
2. Use the UploadId to upload the parts with Upload Part - Copy.
3. Complete the multipart upload with Complete Multipart Upload.
Resuming a multipart upload
1. If you did not record the UploadId of the multipart upload, you can query the multipart upload job with List Multipart Uploads to get the UploadId of the corresponding file.
2. Use the UploadId to list the uploaded parts with List Parts.
3. Use the UploadId to upload the remaining parts with Upload Part.
4. Complete the multipart upload with Complete Multipart Upload.
Aborting a multipart upload
1. If you did not record the UploadId of the multipart upload, you can query the multipart upload job with List Multipart Uploads to get the UploadId of the corresponding file.
2. Abort the multipart upload and delete the uploaded parts with Abort Multipart Upload.
Querying multipart uploads
Description
This API (List Multipart Uploads) is used to query in-progress multipart uploads in a specified bucket.
Sample code
try
{
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());
}
Note:
For the complete sample, go to GitHub. Initializing a multipart upload
Description
This API is used to initialize a multipart upload operation and get its uploadId.
Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
InitMultipartUploadRequest request = new InitMultipartUploadRequest(bucket, key);
InitMultipartUploadResult result = cosXml.InitMultipartUpload(request);
this.uploadId = result.initMultipartUpload.uploadId;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub. Uploading parts
Description
This API (Upload Part) is used to upload an object in parts.
Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string uploadId = "exampleUploadId";
int partNumber = 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);
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());
}
Note:
For the complete sample, go to GitHub. Querying uploaded parts
Description
This API (List Parts) is used to query the uploaded parts of a multipart upload.
Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string uploadId = "exampleUploadId";
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());
}
Note:
For the complete sample, go to GitHub. Completing a multipart upload
Description
This API (Complete Multipart Upload) is used to complete the multipart upload of a file.
Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string uploadId = "exampleUploadId";
CompleteMultipartUploadRequest request = new CompleteMultipartUploadRequest(bucket,
key, uploadId);
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());
}
Note:
For the complete sample, go to GitHub. Aborting a multipart upload
Description
This API (Abort Multipart Upload) is used to abort a multipart upload and delete the uploaded parts.
Sample code
try
{
string bucket = "examplebucket-1250000000";
string key = "exampleobject";
string uploadId = "exampleUploadId";
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());
}
Note:
For the complete sample, go to GitHub. 
