This topic describes how to upload objects to a versioning-enabled bucket by using simple upload, append upload, or multipart upload.

Simple upload

When you upload an object to a versioning-enabled bucket, OSS automatically adds a unique version ID for the uploaded object, and returns the version ID as the x-oss-version-id field in the response header. In a versioning-suspended bucket, the version ID added to an upload object is null. If you upload an object with the same name as an existing object to a versioning-suspended bucket, the existing object is overwritten. In this case, each object only has one version of which the ID is null.

The following code provides an example for simple upload:
# -*- coding: utf-8 -*-
import oss2

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

# Upload an object.
result = bucket.put_object('<yourObjectName>', 'content of object')
# Obtain the returned HTTP status code.
print('http status: {0}'.format(result.status))
# View the version ID of the uploaded object.
print('put object version:', result.versionid)

For more information about simple upload, see PutObject.

Append upload

In a versioning-enabled bucket, the AppendObject operation can be performed only on objects of which the current version is an appendable object.
Note
  • When you perform the AppendObject operation on an object of which the current version is an appendable object, OSS does not generate a previous version for the appendable object.
  • When you perform the PutObject or DeleteObject operation on an object of which the current version is an appendable object, OSS stores the appendable object as a previous version and prevents the object from being further appended.
  • You cannot perform the AppendObject operation on objects of which the current version is not an appendable object such as a normal object or a delete marker.
The following code provides an example for append upload:
# -*- coding: utf-8 -*-
import oss2

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

# Set the position for the first upload (the Position parameter) to 0.
result = bucket.append_object('<yourObjectName>', 0, 'content of first append')
# View the version ID of the object that is appended.
print('append object versionid:', result.versionid)
# If you have performed the AppendObject operation on the object before, you can obtain the position from where the operation starts this time from the next_position field in the response returned in the last operation or by using the bucket.head_object method.
bucket.append_object('<yourObjectName>', result.next_position, 'content of second append')

For more information about append upload, see AppendObject.

Multipart upload

If you call CompleteMultipartUpload to complete the MultipartUpload task for an object in a versioning-enabled bucket, OSS generates a unique version ID for the object and returns it as the x-oss-version-id field in the response header.

The following code provides an example for multipart upload:
# -*- coding: utf-8 -*-
import os
import oss2
from oss2 import SizedFileAdapter, determine_part_size
from oss2.models import PartInfo

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# The endpoint of the China (Hangzhou) region is used in this example. Specify the actual endpoint.
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

key = '<yourObjectName>'
filename = '<yourLocalFile>'

total_size = os.path.getsize(filename)
# The determine_part_size method is used to determine the part size.
part_size = determine_part_size(total_size, preferred_size=100 * 1024)

# Initialize a multipart upload task.
upload_id = bucket.init_multipart_upload(key).upload_id
parts = []

# Upload the parts one by one.
with open(filename, 'rb') as fileobj:
    part_number = 1
    offset = 0
    while offset < total_size:
        num_to_upload = min(part_size, total_size - offset)
    # The SizedFileAdapter(fileobj, size) method generates a new object, and resets the append position.
        result = bucket.upload_part(key, upload_id, part_number,
                                    SizedFileAdapter(fileobj, num_to_upload))
        parts.append(PartInfo(part_number, result.etag))

        offset += num_to_upload
        part_number += 1

# Complete the multipart upload task.
result = bucket.complete_multipart_upload(key, upload_id, part_info_list)
# View the version ID of the uploaded object, which is returned in the response.
print('result.versionid:', result.versionid)


# Verify the result of the multipart upload task.
with open(filename, 'rb') as fileobj:
    assert bucket.get_object(key).read() == fileobj.read()

For more information about multipart upload, see CompleteMultipartUpload.