Resumable download (C++ SDK) - Object Storage Service - Alibaba Cloud Documentation Center

You may fail to download a large object if the network is unstable or other exceptions occur. In some cases, you may fail to download the object even after multiple attempts. To resolve this issue, Object Storage Service (OSS) provides the resumable download feature. In resumable download, OSS splits an object into multiple parts and downloads each part separately. After all parts are downloaded, OSS combines the parts into a complete object.

Usage notes

In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient by using custom domain names or Security Token Service (STS), see Create an OSSClient instance.
To use resumable download, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Implementation method

You can use the `OssClient.ResumableDownloadObject` method to perform a resumable download. The `DownloadObjectRequest` for this method includes the following parameters:

Parameter	Description	Required	Default value	How to set
bucket	The name of the bucket.	Yes	None	Set in the constructor.
key	The full path of the OSS file.	Yes	None	Set in the constructor.
filePath	The full path of the local file.	No	The name of the OSS file	Set in the constructor.
partSize	The shard size. The value must be between 100 KB and 5 GB.	No	8 MB	Set using setPartSize.
threadNum	The number of concurrent shard downloads.	No	3	Set in the constructor or using setThreadNum.
checkpointDir	The file that records the local shard download results. Set this parameter to enable the resumable download feature. Progress information is saved to this file during the download. If a shard fails to download, the next download attempt resumes from the point recorded in the file. After the download is complete, this file is deleted.	No	The same folder as the download file.	Set in the constructor or using setCheckpointDir.

Code sample

The following code shows how to perform a resumable download:

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

int main(void)
{
    /* Initialize OSS account information. */
            
    /* Set yourEndpoint to the Endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Set yourRegion to the Region ID of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region ID to cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Specify the bucket name, for example, examplebucket. */
    std::string BucketName = "examplebucket";
    /* Specify the full path of the object. The full path cannot contain the bucket name. For example, exampledir/exampleobject.txt. */
    std::string ObjectName = "exampledir/exampleobject.txt";
    /* Download the object to a local file named examplefile.txt and save it to the specified local path (D:\\localpath). If the local file exists, it is overwritten. If it does not exist, it is created. */
    /* If you do not specify a local path, the downloaded file is saved to the local path of the project by default. */
    std::string DownloadFilePath = "D:\\localpath\\examplefile.txt";
    /* Set the folder for the breakpoint record file and make sure the specified folder exists, for example, D:\\localpath. */
    /* If an object download is interrupted and a breakpoint record file is generated, you must set the corresponding breakpoint record file to resume the download. After the download is complete, this file is deleted. */
    std::string CheckpointFilePath = "D:\\localpath";

    /* Initialize network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Obtain access credentials from environment variables. Before you run this code sample, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    /* Perform a resumable download. */
    DownloadObjectRequest request(BucketName, ObjectName, DownloadFilePath, CheckpointFilePath);
    auto outcome = client.ResumableDownloadObject(request);

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

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

References

For the complete sample code for resumable downloads, see GitHub sample.
For more information about the API operation for resumable downloads, see GetObject.