This document provides an overview of APIs and SDK sample codes related to uploading and replicating objects.
Simple operations
API | Operation | Description |
---|---|---|
PUT Object | Uploading an object using simple upload | Uploads an object to a bucket |
POST Object | Uploading an object using HTML form | Uploads an object using HTML form |
PUT Object - Copy | Copying an object (modifying object attributes) | Copies a file to a destination path |
Multipart operations
API | Operation | Description |
---|---|---|
List Multipart Uploads | Queries multipart uploads | Queries in-progress multipart uploads |
Initiate Multipart Upload | Initializing a multipart upload | Initializes a multipart upload |
Upload Part | Uploading a part | Uploads a part in multipart upload |
Upload Part - Copy | Copying a part | Copies an object as a part |
List Parts | Querying uploaded parts | Queries the uploaded parts of a specific multipart upload |
Complete Multipart Upload | Completing a multipart upload | Completes the multipart upload of an entire file |
Abort Multipart Upload | Aborting a multipart upload | Aborts a multipart upload and deletes the uploaded parts |
For the parameters and method descriptions of all the APIs in the SDK, see Api Documentation.
The advanced upload API encapsulates both PUT Object (simple upload) and multipart upload APIs, and can automatically select the upload method based on file size. It also supports checkpoint restart for resuming a suspended multipart upload.
// Initialize TransferConfig
TransferConfig transferConfig = new TransferConfig();
// Initialize TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
String bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
String cosPath = "exampleobject"; // Identifier of the object in the bucket, i.e., the object key
String srcPath = @"temp-source-file";// Absolute path to the local file
// An object to upload
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);
}
Note:
- For the complete sample, go to GitHub.
- You can generate a download URL for the uploaded file using the same key. For detailed directions, see Generating a Pre-Signed Link. Please note that for private-read files, the download URL is only valid for a limited period of time.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string cosPath = "exampleobject"; // Object key
byte[] data = new byte[1024]; // Binary data
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, data);
cosXml.PutObject(putObjectRequest);
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
- For the complete sample, go to GitHub.
- You can generate a download URL for the uploaded file using the same key. For detailed directions, see Generating a Pre-Signed Link. Please note that for private-read files, the download URL is only valid for a limited period of time.
To suspend an upload, use the code below:
uploadTask.Pause();
To resume a suspended download, run the code below:
uploadTask.Resume();
To cancel an upload, run this code:
uploadTask.Cancel();
Note:
- For the complete sample, go to GitHub.
TransferConfig transferConfig = new TransferConfig();
// Initialize TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
for (int i = 0; i < 5; i++) {
// A set of objects to upload
string cosPath = "exampleobject" + i; // The location identifier of an object in the bucket, i.e. the object key
string srcPath = @"temp-source-file";// Absolute path to the local file
COSXMLUploadTask uploadTask = new COSXMLUploadTask(bucket, cosPath);
uploadTask.SetSrcPath(srcPath);
await transferManager.UploadAsync(uploadTask);
}
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string cosPath = "dir/"; // Object key
PutObjectRequest putObjectRequest = new PutObjectRequest(bucket, cosPath, new byte[0]);
cosXml.PutObject(putObjectRequest);
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
- For the complete sample, go to GitHub.
- You can generate a download URL for the uploaded file using the same key. For detailed directions, see Generating a Pre-Signed Link. Please note that for private-read files, the download URL is only valid for a limited period of time.
The advanced replication API encapsulates PUT Object - Copy, and the APIs for multipart replication to allow asynchronous requests for suspending, resuming and canceling a replication request.
string sourceAppid = "1250000000"; // Account APPID
string sourceBucket = "sourcebucket-1250000000"; // Bucket of the source object
string sourceRegion = "COS_REGION"; // Region where the bucket of the source object resides
string sourceKey = "sourceObject"; // Key of the source object
// Construct the source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);
string bucket = "examplebucket-1250000000"; // Destination bucket in the format: BucketName-APPID
string key = "exampleobject"; // Key of the destination object
COSXMLCopyTask copytask = new COSXMLCopyTask(bucket, key, copySource);
try {
COSXML.Transfer.COSXMLCopyTask.CopyTaskResult result = await
transferManager.CopyAsync(copytask);
Console.WriteLine(result.GetResultInfo());
string eTag = result.eTag;
} catch (Exception e) {
Console.WriteLine("CosException: " + e);
}
Note:
For the complete sample, go to GitHub.
This API is used to upload an object to a specified bucket. This operation requires the requester to have WRITE permission for the bucket and can upload a file of up to 5 GB in size. To upload larger objects, please use Multipart Upload or the advanced upload API.
Note:
- The Key (file name) 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. If you do not need ACL control over an object, please leave it to the default option of inheriting bucket permissions.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string srcPath = @"temp-source-file";// Absolute path to the local file
PutObjectRequest request = new PutObjectRequest(bucket, key, srcPath);
// Set progress callback
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
// Execute the request
PutObjectResult result = cosXml.PutObject(request);
// Object Etag
string eTag = result.eTag;
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
- For the complete sample, go to GitHub.
- You can generate a download URL for the uploaded file using the same key. For detailed directions, see Generating a Pre-Signed Link. Please note that for private-read files, the download URL is only valid for a limited period of time.
This API is used to upload an object using an HTML form.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string srcPath = @"temp-source-file";// Absolute path to the local file
PostObjectRequest request = new PostObjectRequest(bucket, key, srcPath);
// Set progress callback
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
// Execute the request
PostObjectResult result = cosXml.PostObject(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to copy a file to a destination path.
try
{
string sourceAppid = "1250000000"; // Account APPID
string sourceBucket = "sourcebucket-1250000000"; // Bucket of the source object
string sourceRegion = "COS_REGION"; // Region where the bucket of the source object resides
string sourceKey = "sourceObject"; // Key of the source object
// Construct the source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
CopyObjectRequest request = new CopyObjectRequest(bucket, key);
// Set the copy source
request.SetCopySource(copySource);
// Set whether to copy or update. Copy is used here.
request.SetCopyMetaDataDirective(COSXML.Common.CosMetaDataDirective.Copy);
// Execute the request
CopyObjectResult result = cosXml.CopyObject(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
try
{
string sourceAppid = "1250000000"; // Account APPID
string sourceBucket = "sourcebucket-1250000000"; // Bucket of the source object
string sourceRegion = "COS_REGION"; // Region where the bucket of the source object resides
string sourceKey = "sourceObject"; // Key of the source object
// Construct the source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
CopyObjectRequest request = new CopyObjectRequest(bucket, key);
// Set the copy source
request.SetCopySource(copySource);
// Set whether to copy or update. Copy is used here.
request.SetCopyMetaDataDirective(COSXML.Common.CosMetaDataDirective.Replaced);
// Replace metadata
request.SetRequestHeader("Content-Disposition", "attachment; filename=example.jpg");
// Execute the request
CopyObjectResult result = cosXml.CopyObject(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string appId = "1250000000"; // Account APPID
string region = "COS_REGION"; // Region where the bucket of the source object resides
// Construct object attributes
CopySourceStruct copySource = new CopySourceStruct(appId, bucket,
region, key);
CopyObjectRequest request = new CopyObjectRequest(bucket, key);
// Set the copy source
request.SetCopySource(copySource);
// Set whether to copy or update. Copy is used here.
request.SetCopyMetaDataDirective(COSXML.Common.CosMetaDataDirective.Replaced);
// Replace metadata
request.SetRequestHeader("Content-Disposition", "attachment; filename=example.jpg");
request.SetRequestHeader("Content-Type", "image/png");
// Execute the request
CopyObjectResult result = cosXml.CopyObject(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string appId = "1250000000"; // Account APPID
string region = "COS_REGION"; // Region where the bucket of the source object resides
// Construct object attributes
CopySourceStruct copySource = new CopySourceStruct(appId, bucket,
region, key);
CopyObjectRequest request = new CopyObjectRequest(bucket, key);
// Set the copy source
request.SetCopySource(copySource);
// Set whether to copy or update. Copy is used here.
request.SetCopyMetaDataDirective(COSXML.Common.CosMetaDataDirective.Replaced);
// Modify the storage class to ARCHIVE
request.SetCosStorageClass("ARCHIVE");
// Execute the request
CopyObjectResult result = cosXml.CopyObject(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
The multipart operation process is outlined below.
Initiate Multipart Upload
and get the UploadId
.UploadId
to upload parts with Upload Part
or copy parts with Upload Part Copy
Complete Multipart Upload
.UploadId
of the multipart upload, you can query the multipart upload with List Multipart Uploads
to get it.UploadId
to list the uploaded parts with List Parts
.UploadId
to upload the remaining parts with Upload Part
or copy the remaining parts with Upload Part - Copy
.Complete Multipart Upload
.UploadId
of the multipart upload, you can query the multipart upload with List Multipart Uploads
to get it.Abort Multipart Upload
.This API is used to query in-progress multipart uploads in a specified bucket.
try
{
string bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
ListMultiUploadsRequest request = new ListMultiUploadsRequest(bucket);
// Execute the request
ListMultiUploadsResult result = cosXml.ListMultiUploads(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to initialize a multipart upload, and get its uploadId.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
InitMultipartUploadRequest request = new InitMultipartUploadRequest(bucket, key);
// Execute the request
InitMultipartUploadResult result = cosXml.InitMultipartUpload(request);
// Request succeeded
this.uploadId = result.initMultipartUpload.uploadId; // The uploadId to use for subsequent multipart uploads
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to upload parts in a multipart upload.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // uploadId returned when the multipart upload was initialized
int partNumber = 1; // Part number that increases starting from 1
string srcPath = @"temp-source-file";// Absolute path to the local file
UploadPartRequest request = new UploadPartRequest(bucket, key, partNumber,
uploadId, srcPath, 0, -1);
// Set progress callback
request.SetCosProgressCallback(delegate (long completed, long total)
{
Console.WriteLine(String.Format("progress = {0:##.##}%", completed * 100.0 / total));
});
// Execute the request
UploadPartResult result = cosXml.UploadPart(request);
// Request succeeded
// Return Etag of the part for subsequent CompleteMultiUploads
this.eTag = result.eTag;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to copy an object as a part.
try
{
string sourceAppid = "1250000000"; // Account APPID
string sourceBucket = "sourcebucket-1250000000"; // Bucket of the source object
string sourceRegion = "COS_REGION"; // Region where the bucket of the source object resides
string sourceKey = "sourceObject"; // Key of the source object
// Construct the source object attributes
COSXML.Model.Tag.CopySourceStruct copySource = new CopySourceStruct(sourceAppid,
sourceBucket, sourceRegion, sourceKey);
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string uploadId = this.uploadId; // uploadId returned when the multipart upload was initialized
int partNumber = 1; // Part number that increases starting from 1
UploadPartCopyRequest request = new UploadPartCopyRequest(bucket, key,
partNumber, uploadId);
// Set the copy source
request.SetCopySource(copySource);
// Set the byte range of an object to copy as a part, e.g., 0 to 1 M
request.SetCopyRange(0, 1024 * 1024);
// Execute the request
UploadPartCopyResult result = cosXml.PartCopy(request);
// Request succeeded
// Return Etag of the part for subsequent CompleteMultiUploads
this.eTag = result.copyPart.eTag;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to query the uploaded parts of a specific multipart upload.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // uploadId returned when the multipart upload was initialized
ListPartsRequest request = new ListPartsRequest(bucket, key, uploadId);
// Execute the request
ListPartsResult result = cosXml.ListParts(request);
// Request succeeded
// List the parts that have been uploaded
List<COSXML.Model.Tag.ListParts.Part> alreadyUploadParts = result.listParts.parts;
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to complete the multipart upload of an entire file.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // uploadId returned when the multipart upload was initialized
CompleteMultipartUploadRequest request = new CompleteMultipartUploadRequest(bucket,
key, uploadId);
// Specify uploaded parts in an ascending order by partNumber
request.SetPartNumberAndETag(1, this.eTag);
// Execute the request
CompleteMultipartUploadResult result = cosXml.CompleteMultiUpload(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
This API is used to abort a multipart upload and delete the uploaded parts.
try
{
string bucket = "examplebucket-1250000000"; // Bucket name in the format: BucketName-APPID
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // uploadId returned when the multipart upload was initialized
AbortMultipartUploadRequest request = new AbortMultipartUploadRequest(bucket, key, uploadId);
// Execute the request
AbortMultipartUploadResult result = cosXml.AbortMultiUpload(request);
// Request succeeded
Console.WriteLine(result.GetResultInfo());
}
catch (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}
Note:
For the complete sample, go to GitHub.
Was this page helpful?