This topic describes how to copy objects in a versioned bucket. You can use CopyObject to copy an object that is up to 1 GB in size and use UploadPartCopy to copy an object larger than 1 GB.

Copy a small object

You can use CopyObject to copy an object that is up to 1 GB in size from a source bucket to a destination bucket within the same region.

  • By default, the x-oss-copy-source header in a CopyObject request specifies the current version of the object to copy. If the current version of the object is a delete marker, Object Storage Service (OSS) returns 404, which indicates that the object does not exist. You can add a version ID to x-oss-copy-source to copy the specified object version. Delete markers cannot be copied.
  • You can copy a previous version of an object to the same bucket. The copied previous version becomes the new version of the object. This way, the previous version of the object is recovered.
  • If versioning is enabled for the destination bucket, OSS generates a unique version ID for the destination object. The version ID is returned in the response as the x-oss-version-id header value. If versioning is not enabled or is suspended for the destination bucket, OSS generates a version whose version ID is null for the destination object and overwrites the original version whose version ID is null.
  • If versioning is not enabled for the destination bucket, you can copy append objects. If versioning is enabled or suspended for the destination bucket, you cannot copy append objects.
The following code provides an example on how to copy a small object:
# -*- coding: utf-8 -*-
import oss2
# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
# Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
src_object_name = 'srcexampledir/exampleobject.txt'
# Specify the full path of the destination object. Example: destexampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
dest_object_name = 'destexampledir/exampleobject.txt'
# Specify the version ID of the source object. 
versionId = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

# Copy the specified version of the object. 
params = dict()
params['versionId'] = versionId
result = bucket.copy_object(bucket.bucket_name, src_object_name, dest_object_name, params=params)
# Display the version ID of the destination object. 
print('result.versionid:', result.versionid)

For more information about how to copy small objects, see CopyObject.

Copy a large object

To copy an object larger than 1 GB, you must split the object into parts and copy them sequentially by using UploadPartCopy.

By default, the UploadPartCopy operation uploads a part by copying data from the current version of an existing object. You can add versionId in the request header x-oss-copy-source as the condition to upload a part by copying data from a specified version of an existing object. Example: x-oss-copy-source : /SourceBucketName/SourceObjectName?versionId=CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****.
Note The value of SourceObjectName must be URL-encoded. The version ID of the copied object is returned in the response. The returned version ID is x-oss-copy-source-version-id.

If versionId is not specified in the request and the current version of the source object is a delete marker, OSS returns 404 Not Found. If versionId is specified in the request and the specified version of the source object is a delete marker, OSS returns 400 Bad Request.

The following code provides an example on how to copy parts:
# -*- coding: utf-8 -*-
import os
import oss2
from oss2 import determine_part_size
from oss2.models import PartInfo

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'yourEndpoint', 'examplebucket')
# Specify the full path of the source object. Example: srcexampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
src_object_name = 'srcexampledir/exampleobject.txt'
# Specify the full path of the destination object. Example: destexampledir/exampleobject.txt. The full path of the object cannot contain bucket names. 
dest_object_name = 'destexampledir/exampleobject.txt'
# Specify the version ID of the object. 
versionId = 'CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****'

params = dict()
params['versionId'] = versionId

# Query the size of the specified version of the source object. 
head_info = bucket.head_object(src_object_name, params=params)
total_size = head_info.content_length
print('src object size:', total_size)

# The determine_part_size method is used to determine the part size. 
part_size = determine_part_size(total_size, preferred_size=100 * 1024)
print('part_size:', part_size)

# Initiate a multipart copy task. 
upload_id = bucket.init_multipart_upload(dest_object_name).upload_id
parts = []

# Upload the parts one by one. 
part_number = 1
offset = 0
while offset < total_size:
    num_to_upload = min(part_size, total_size - offset)
    end = offset + num_to_upload - 1;
    result = bucket.upload_part_copy(bucket.bucket_name, src_object_name, (offset, end), dest_object_name, upload_id, part_number, params=params)
    # Save the part information. 
    parts.append(PartInfo(part_number, result.etag))

    offset += num_to_upload
    part_number += 1

# Complete the multipart upload task. 
result = bucket.complete_multipart_upload(dest_object_name, upload_id, parts)
# Display the version ID of the destination object. 
print('result version id:', result.versionid)
# Obtain the metadata of the destination object. 
head_info = bucket.head_object(dest_object_name)
# View the size of the destination object. 
dest_object_size = head_info.content_length
print('dest object size:', dest_object_size)
# Compare the sizes between the source and destination objects. 
assert dest_object_size == total_size

For more information about multipart copy, see UploadPartCopy.