Before you upload an object to Object Storage Service (OSS) by using resumable upload, you can specify a directory for the checkpoint file that stores resumable upload records. If an object fails to upload due to a network exception or program error, the upload task is resumed from the position recorded in the checkpoint file to upload the remaining data.

Background information

During resumable upload, the upload progress is recorded in a checkpoint file. If the upload of a part fails, the next upload starts from the position recorded in the checkpoint file. After resumable upload is complete, the checkpoint file is deleted.

Notice
  • The SDK records the upload progress in the checkpoint file. Ensure that you have write permissions on the checkpoint file. The checkpoint file contains a checksum. This checksum cannot be edited. If the checkpoint file is damaged, you must upload all parts again.
  • If the local file to upload is modified during the upload, you must upload the entire object again.

You can use the Bucket.UploadFile method to perform resumable upload. The following table describes the parameters you can configure for this operation.

Parameter Description
objectKey The name of the object.
filePath The local file path from which to upload the object.
partSize The size of each part. Valid values: 100 KB to 5 GB. Default value: 100 KB.
options Valid values:
  • Routines: specifies the number of concurrent upload threads. The default value is 1, which indicates that only one thread is used to upload the parts.
  • Checkpoint: specifies whether resumable upload is enabled and the path of the checkpoint file. By default, resumable upload is disabled.

    For example, oss.Checkpoint(true, "") indicates that resumable upload is enabled and the checkpoint file is the file.cp file contained in the same directory as the source local file. file is the name of the local file to upload. You can also use oss.Checkpoint(true, "your-cp-file.cp") to specify the checkpoint file.

Note For more information about other metadata, see Manage object metadata.

Implementation method

You can call the client.ResumableUploadObject method to perform resumable upload. The following table describes the parameters you can configure for UploadObjectRequest.

Parameter Description Required Default value Configuration method
bucket The name of the bucket. Yes None Constructor
key The name of the object uploaded to OSS. Yes None
filePath The name of the local file to upload. No None
partSize The size of each part to upload. Valid values: 100 KB to 5 GB. No 8 MB setPartSize
threadNum The number of parts to upload simultaneously. No 3 Constructor or setThreadNum
checkpointDir The checkpoint file that records the results of the multipart upload task. This file stores information about upload progress. If a part cannot be uploaded, the task can be resumed based on the progress recorded in the checkpoint file. After the object is uploaded, the checkpoint file is deleted. No The directory in which the local file to upload is stored. Constructor or setCheckpointDir

Sample code

The following code provides an example on how to perform resumable upload by using multipart upload:

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

int main(void)
{
    /* Initialize the information about the account used to access OSS. */
    /* 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. */
    std::string AccessKeyId = "yourAccessKeyId";
    std::string AccessKeySecret = "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 the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Specify the full path of the local file. Example: D:\\localpath\\examplefile.txt. By default, if you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs. */
    std::string UploadFilePath = "D:\\localpath\\examplefile.txt";
    /* Specify the checkpoint file that records the results of the multipart upload task. This file stores information about upload progress. If a part cannot be uploaded, the task can be resumed based on the progress recorded in the checkpoint file. After the object is uploaded, the checkpoint file is deleted. */
    /* By default, if you do not specify the path of the checkpoint file, the checkpoint file and the local file to upload share the same path. */
    std::string CheckpointFilePath = "yourCheckpointFilepath"

    /* Initialize resources such as networks. */
    InitializeSdk();

    ClientConfiguration conf;
    OssClient client(Endpoint, AccessKeyId, AccessKeySecret, conf);

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

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

    /* Release resources such as networks. */
    ShutdownSdk();
    return 0;
}

References

For more information about the complete sample code for resumable upload, visit GitHub.