Upload objects with resumable upload using the C++ SDK - Object Storage Service

Resumable upload splits a large file into parts and tracks progress in a checkpoint file. If the upload is interrupted by a network exception or program error, the next call automatically resumes from the last successful part instead of restarting the entire upload.

Use resumable upload when:

Networks are unstable — only the failed parts are retried, not the entire file.
Files are large — parts are uploaded in parallel, making better use of available bandwidth.

For small files on reliable connections, a standard PutObject call is simpler.

Usage notes

This topic uses the public endpoint for the China (Hangzhou) region. To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. For region-endpoint mappings, see Regions and endpoints.
To create an OSSClient instance using a custom domain or Security Token Service (STS), see Create an OSSClient instance.
To use resumable upload, you must have the oss:PutObject permission. For details, see Attach a custom policy to a RAM user.
Upload progress is saved to a checkpoint file. If a part fails, the next upload attempt resumes from the position recorded in that file. The checkpoint file is deleted after the upload completes.
The checkpoint file contains a checksum and cannot be modified. If the checkpoint file is damaged, or if the local file is modified during the upload, all parts must be re-uploaded from the beginning.

Important

Parts that are uploaded but never assembled into a complete object still occupy storage and incur charges. To avoid unexpected costs from interrupted uploads, configure a lifecycle rule on the bucket to abort incomplete multipart uploads after a set number of days.

Implementation

Use client.ResumableUploadObject to perform a resumable upload. The UploadObjectRequest accepts the following parameters:

Parameter	Required	Default	How to set	Description
`bucket`	Yes	—	Constructor	The bucket name
`key`	Yes	—	Constructor	The object key (full path in OSS, excluding the bucket name)
`filePath`	No	—	Constructor	The full path of the local file to upload
`partSize`	No	8 MB	`setPartSize`	The size of each part. Valid range: 100 KB to 5 GB. For large files on high-bandwidth connections, increase this value to reduce the total number of parts and API calls
`threadNum`	No	3	Constructor or `setThreadNum`	The number of concurrent threads for multipart upload. Increase this value to improve throughput on high-bandwidth connections; reduce it if the upload competes with other network-sensitive workloads
`checkpointDir`	No	Same folder as the download file	Constructor or `setCheckpointDir`	The directory where the checkpoint file is stored. The directory must exist before the upload starts. If not set, progress is not saved and the upload cannot resume after interruption

Sample code

The following example uploads a local file to OSS using ResumableUploadObject.

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    // Set the endpoint for the region where your bucket is located.
    // Example for China (Hangzhou): https://oss-cn-hangzhou.aliyuncs.com
    std::string Endpoint = "https://oss-cn-hangzhou.aliyuncs.com";

    // Set the region ID. Example: cn-hangzhou
    std::string Region = "cn-hangzhou";

    // Bucket name.
    std::string BucketName = "examplebucket";

    // Full object path in OSS (excluding the bucket name).
    // Example: exampledir/exampleobject.txt
    std::string ObjectName = "exampledir/exampleobject.txt";

    // Full path of the local file to upload.
    // Example: D:\\localpath\\examplefile.txt
    std::string UploadFilePath = "D:\\localpath\\examplefile.txt";

    // Directory where the checkpoint file is stored.
    // The directory must exist before the upload starts. If not set, progress is not
    // saved and the upload cannot resume after interruption.
    // Example: D:\\local
    std::string CheckpointFilePath = "D:\\local";

    // Initialize network and other resources.
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;

    // Load credentials from environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    // Start the resumable upload.
    UploadObjectRequest request(BucketName, ObjectName, UploadFilePath, CheckpointFilePath);
    auto outcome = client.ResumableUploadObject(request);

    if (!outcome.isSuccess()) {
        std::cout << "ResumableUploadObject failed"
                  << ", code: "      << outcome.error().Code()
                  << ", message: "   << outcome.error().Message()
                  << ", requestId: " << outcome.error().RequestId()
                  << std::endl;
        return -1;
    }

    // Release network and other resources.
    ShutdownSdk();
    return 0;
}

References

For the complete sample code, see GitHub sample.