Docs

Torch Object Storage

Upload Object

Multipart Upload (C++ SDK)

For larger objects, the data can be divided into multiple data blocks (parts) and uploaded separately. Finally, the merge parts operation is invoked to combine the uploaded data blocks into a single object.

Precautions

Before initiating a multipart upload, you must have the tos:PutObject permission. For detailed instructions, please refer to the Permissions Configuration Guide.

Before canceling a multipart upload task, you must have the tos:AbortMultipartUpload permission. For specific steps, see the Permissions Configuration Guide.

Shard numbering starts at 1 and has a maximum value of 10,000. Except for the last fragment, the minimum size of the other fragments is 4 MiB.

When uploading objects, object names must comply with specific standards. For detailed information, please refer to Object Naming Guidelines.

TOS is a distributed object storage product designed for large-scale storage, with internal partitions storing object index data. To maximize horizontal scalability for uploading and downloading objects and to reduce the likelihood of hotspot partitions, please avoid using object names that increase lexicographically. For more information, see Performance Optimization.

If an object with the same name already exists in the bucket, the new object will overwrite the existing one. If versioning is enabled for your bucket, the original object will be retained, and a new version number will be generated to identify the newly uploaded object.

Chunked Upload Procedure

Multipart upload generally consists of the following three steps:

Initialize multipart upload task.

Before uploading multipart data, you must first initialize the multipart upload and obtain an uploadID via the createMultipartUpload API. For subsequent operations such as uploading parts, merging parts, aborting the multipart upload, and listing uploaded parts, you need to pass in the uploadID parameter. Initializing a multipart upload task does not affect any existing objects with the same name.

Upload chunk.

Use this interface to upload data parts. You must specify the uploadID obtained via createMultipartUpload, as well as the part number, which must be within the range [1, 10000]. For the same object and the same multipart upload task, multiple parts can be uploaded concurrently, and the order of upload does not affect the final merge operation.

The SDK supports direct multipart upload via uploadPart, as well as file-based multipart upload via uploadPartFromFile.

tip

For the same multipart upload task (identified by uploadId), the part number (partNumber) indicates the relative position of the part within the entire object. If data is uploaded multiple times using the same shard identifier, TOS will overwrite the original data and retain only the most recently uploaded version.

The response header contains the MD5 value of the data, which can be obtained via the ETag. When merging parts, you must specify all part information (part number and ETag value) from the current multipart upload task.

Multipart upload completed.

After all parts have been uploaded, invoke the completeMultipartUpload method to merge all parts into a single complete object.

Sample Code

Complete Process of Multipart Upload

The following code uploads a local file to the object exampledir/exampleobject.txt in the target bucket examplebucket using multipart upload. During upload, specify the ACL as PublicRead, set the storage type to infrequent access, and add custom metadata.

List information of uploaded file fragments

The following code is used to list the uploaded part information for the object exampledir/exampleobject.txt in the bucket examplebucket.

Cancel Multipart Upload Task

You can cancel a multipart upload task by using the abortMultipartUpload method. Once a multipart upload task is canceled, TOS will delete all previously uploaded part data, and you will no longer be able to perform any operations on this multipart upload task.

The following code is used to cancel the multipart upload task for the object exampledir/exampleobject.txt in the bucket examplebucket.

Relevant Documents

For the API documentation on creating a multipart upload task, see CreateMultipartUpload.

For API documentation on uploading parts, please refer to UploadPart.

For API documentation on completing multipart uploads, refer to CompleteMultipartUpload.

For API documentation on aborting multipart upload tasks, please refer to AbortMultipartUpload.

Last updated: 2025.09.25 14:22:47