tencent cloud

All product documents
Cloud Object Storage
Copying and Moving Objects
Last updated: 2024-02-02 14:36:36
Copying and Moving Objects
Last updated: 2024-02-02 14:36:36

Overview

This document provides an overview of APIs and SDK code samples related to object copy and movement.
Simple operations
API
Operation
Description
Copying an object (modifying object attributes)
Copies a file to a destination path.
Deleting an object
Deletes a specified object from a bucket.
Multipart operations
API
Operation
Description
Querying parts
Queries in-progress parts.
Initializing a part
Initializes a part.
Copying a part
Copies an object as a part.
Querying copied/uploaded parts
Queries the copied/uploaded parts of a multipart operation.
Completing a multipart upload/copy
Completes the multipart upload/copy of a file.
Aborting a multipart upload/copy
Aborts a multipart operation and deletes the uploaded/copied parts.

Advanced APIs (Recommended)

Copying objects

Description

The advanced APIs encapsulate async requests for the simple copy and multipart copy APIs and support pausing, resuming, and canceling copy requests.
Note:
If the object size is less than the multipart copy threshold, simple copy is used. Otherwise, multiple copy is used. The multipart copy threshold is configurable and is 5 MB by default.
The part size is configurable and is 2 MB by default.

Sample code

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

namespace COSSnippet
{
public class TransferCopyObjectModel {

private CosXml cosXml;

TransferCopyObjectModel() {
CosXmlConfig config = new CosXmlConfig.Builder()
.SetRegion("COS_REGION") // Set the default region. For abbreviations of COS regions, visit https://www.tencentcloud.com/document/product/436/6224.
.Build();

string secretId = "SECRET_ID"; // SecretId of the TencentCloud API. For more information about how to obtain the API key, see https://console.tencentcloud.com/cam/capi.
string secretKey = "SECRET_KEY"; // SecretKey of the TencentCloud API. For more information about how to obtain the API key, see https://console.tencentcloud.com/cam/capi.
long durationSecond = 600; // Validity period of the request signature in seconds
QCloudCredentialProvider qCloudCredentialProvider = new DefaultQCloudCredentialProvider(secretId,
secretKey, durationSecond);

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

/// Copy an object via advanced API
public async Task TransferCopyObject()
{
TransferConfig transferConfig = new TransferConfig();
// Manually set the multipart copy threshold. If the object size is less than the threshold, simple copy is used. Otherwise, multipart copy is used. If no value is specified, the default value 5 MB is used.
transferConfig.DdivisionForCopy = 5242880;
// Manually set the automatic part size for the advanced API. If no value is specified, the default value 2 MB is used.
transferConfig.SliceSizeForCopy = 2097152;

// Initialize TransferManager
TransferManager transferManager = new TransferManager(cosXml, transferConfig);

string sourceAppid = "1250000000"; // Account appid
string sourceBucket = "sourcebucket-1250000000"; //" Source object bucket
string sourceRegion = "COS_REGION"; // Source object bucket region
string sourceKey = "sourceObject"; // Source object key
// Construct source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);

string bucket = "examplebucket-1250000000"; // Destination bucket in the format of BucketName-APPID
string key = "exampleobject"; // Object key of the destination bucket

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 (COSXML.CosException.CosClientException clientEx)
{
// Request failed
Console.WriteLine("CosClientException: " + clientEx);
}
catch (COSXML.CosException.CosServerException serverEx)
{
// Request failed
Console.WriteLine("CosServerException: " + serverEx.GetInfo());
}

}

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

/// Copy an object via advanced API
m.TransferCopyObject().Wait();
}
}
}
Note:
For the complete sample, go to GitHub.

Simple Operations

Copying an object (modifying object attributes)

Description

This API (PUT Object - Copy) is used to copy a file to a destination path. You can set and modify object attributes and metadata in the copy request. The API also supports in-situ copy, which allows you to modify object metadata where it is.

Sample code 1. Copying an object with its attributes preserved

try
{
string sourceAppid = "1250000000"; // Account appid
string sourceBucket = "sourcebucket-1250000000"; //" Source object bucket
string sourceRegion = "COS_REGION"; // Source object bucket region
string sourceKey = "sourceObject"; // Source object key
// Construct source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);

// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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.

Sample code 2. Modifying the storage class of an object

Note:
You can change the storage class of an object from STANDARD to STANDARD_IA, INTELLIGENT TIERING, ARCHIVE, or DEEP ARCHIVE.
To change ARCHIVE or DEEP ARCHIVE to other storage classes, you need to call PostRestore to restore objects in ARCHIVE or DEEP ARCHIVE first before calling this API.
For more details about storage classes, please see Storage Class Overview.
try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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);
// Change 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.

Sample code 3. Copying an object while replacing its attributes

try
{
string sourceAppid = "1250000000"; // Account appid
string sourceBucket = "sourcebucket-1250000000"; //" Source object bucket
string sourceRegion = "COS_REGION"; // Source object bucket region
string sourceKey = "sourceObject"; // Source object key
// Construct source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);

// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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.

Sample code 4. Modifying object metadata

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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.

Moving an object

Object movement involves copying the source object to the target location and deleting the source object.
Since COS uses the bucket name (Bucket) and object key (ObjectKey) to identify objects, moving an object will change the object identifier. Currently, COS .NET SDK does not provide a standalone API to change object identifiers. However, you can still move the object with a combination of basic operations (object copy and object delete).
For example, if you want to move the picture.jpg object to the “doc” directory that is in the same bucket (mybucket-1250000000), you can copy the picture.jpg to the “doc” directory (making the object key doc/picture.jpg) and then delete the source object.
Likewise, if you need to move picture.jpg in the mybucket-1250000000 bucket to another bucket myanothorbucket-1250000000, you can copy the object to the myanothorbucket-1250000000 bucket first and then delete the source object.

Sample code

//: # ".cssg-snippet-move-object"
string sourceAppid = "1250000000"; // Account APPID
// Name of the bucket where the source object resides, in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string sourceBucket = "sourcebucket-1250000000";
string sourceRegion = "COS_REGION"; // Source object bucket region
string sourceKey = "sourceObject"; // Source object key
// Construct source object attributes
CopySourceStruct copySource = new CopySourceStruct(sourceAppid, sourceBucket,
sourceRegion, sourceKey);

// Name of destination bucket, in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; // Object key of the destination bucket

COSXMLCopyTask copyTask = new COSXMLCopyTask(bucket, key, copySource);

try {
// Copy the object.
COSXML.Transfer.COSXMLCopyTask.CopyTaskResult result = await
transferManager.CopyAsync(copyTask);
Console.WriteLine(result.GetResultInfo());

// Delete the object.
DeleteObjectRequest request = new DeleteObjectRequest(sourceBucket, sourceKey);
DeleteObjectResult deleteResult = cosXml.DeleteObject(request);
// Print results.
Console.WriteLine(deleteResult.GetResultInfo());
} catch (Exception e) {
Console.WriteLine("CosException: " + e);
}
Note:
For more samples, please go to GitHub.

Multipart Operations

This section describes the process of multipart copy. COS APIs InitiateMultipartUpload, UploadPart/UploadPartCopy, and `CompleteMultipartUpload APIs can be used for both multipart upload and multipart copy. Therefore, there is a certain degree of overlap between the APIs and usages between multipart copy and multipart upload.

Performing a multipart copy

1. Initialize parts with Initiate Multipart Upload and get the UploadId.
2. Use the UploadId to copy the parts with Upload Part - Copy.
3. Complete the multipart copy with Complete Multipart Upload.

Continuing the multipart copy

1. If you did not record the UploadId of the multipart copy, you can query the multipart copy job with List Multipart Uploads to get the UploadId of the corresponding file.
2. Use the UploadId to list the copied parts with List Parts.
3. Use the UploadId to copy the remaining parts with Upload Part - Copy.
4. Complete the multipart copy with Complete Multipart Upload.

Aborting a multipart copy

1. If you did not record the UploadId of the multipart upload, you can query the multipart copy job with List Multipart Uploads to get the UploadId of the corresponding file.
2. Abort the multipart copy and delete the copied parts with Abort Multipart Upload.

Querying multipart copies

Description

This API (List Multipart Uploads) is used to query in-progress multipart copies in a specified bucket.

Sample code

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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.

Initializing a multipart copy

Description

This API (Initiate Multipart Upload) is used to initialize a multipart copy operation and get its uploadId.

Sample code

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
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 copies
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.

Copying an object part

Description

This API (Upload Part - Copy) is used to copy an object as a part.

Sample code

try
{
string sourceAppid = "1250000000"; // Account appid
string sourceBucket = "sourcebucket-1250000000"; //" Source object bucket
string sourceRegion = "COS_REGION"; // Source object bucket region
string sourceKey = "sourceObject"; // Source object key
// Construct source object attributes
COSXML.Model.Tag.CopySourceStruct copySource = new CopySourceStruct(sourceAppid,
sourceBucket, sourceRegion, sourceKey);

// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; // Object key
string uploadId = this.uploadId; // `uploadId` returned when the multipart upload/copy is initialized
int partNumber = 1; // Part number, increases incrementally starting from 1
UploadPartCopyRequest request = new UploadPartCopyRequest(bucket, key,
partNumber, uploadId);
// Set the copy source
request.SetCopySource(copySource);
// Set the range of parts to be copied, e.g., 0 to 1M
request.SetCopyRange(0, 1024 * 1024);
// Execute the request
UploadPartCopyResult result = cosXml.PartCopy(request);
// Request succeeded
// Get the ETag of the returned 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.

Querying copied parts

Description

This API (List Parts) is used to query the copied parts of a multipart copy.

Sample code

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // `uploadId` returned when the multipart upload/copy is initialized
ListPartsRequest request = new ListPartsRequest(bucket, key, uploadId);
// Execute the request
ListPartsResult result = cosXml.ListParts(request);
// Request succeeded
// List uploaded/copied parts
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.

Completing a multipart copy

Description

This API (Complete Multipart Upload) is used to complete the multipart copy of a file.

Sample code

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // `uploadId` returned when the multipart upload/copy is initialized
CompleteMultipartUploadRequest request = new CompleteMultipartUploadRequest(bucket,
key, uploadId);
// Concatenate copied parts in 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.

Aborting a multipart copy

Description

This API (Abort Multipart Upload) is used to abort a multipart copy and delete the copied parts.

Sample code

try
{
// Bucket name in the format of `BucketName-APPID`. You can get APPID by referring to https://console.tencentcloud.com/developer.
string bucket = "examplebucket-1250000000";
string key = "exampleobject"; // Object key
string uploadId = "exampleUploadId"; // `uploadId` returned when the multipart upload/copy is 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?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support