Object Storage Service:Resumable download (C++ SDK)

When to use resumable download

Use ResumableDownloadObject when:

• The network is unstable or the download may be interrupted by exceptions.

• A full restart on failure is unacceptable for large objects.

Prerequisites

Before you begin, make sure you have:

• An OSS bucket with at least one object to download

• The oss:GetObject permission on the target object — see Attach a custom policy to a RAM user

• The OSS C++ SDK installed and initialized

If your application runs in the same region as your OSS bucket, use the internal endpoint. For endpoint details, see Regions and endpoints.

How it works

1. ResumableDownloadObject splits the object into parts based on the configured part size.

2. Parts are downloaded concurrently using the configured number of threads.

3. If checkpointDir is set, OSS writes progress to a checkpoint file during the download. On failure, the next attempt reads the checkpoint file and skips already-downloaded parts.

4. After all parts are downloaded successfully, OSS combines them into the final file. The checkpoint file is then deleted automatically.

Parameters

ResumableDownloadObject accepts a DownloadObjectRequest object with the following parameters:

How to set each parameter:

• bucket, key, filePath, threadNum, and checkpointDir can be set in the DownloadObjectRequest constructor.

• partSize is set using setPartSize.

• threadNum and checkpointDir can also be set using setThreadNum and setCheckpointDir.

Download an object with resumable download

The following example downloads exampledir/exampleobject.txt from examplebucket to a local file, with checkpoint-based resumability enabled.

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

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

    /* Set the region ID for your bucket.
       For example, cn-hangzhou for China (Hangzhou). */
    std::string Region = "yourRegion";

    /* The name of the bucket. */
    std::string BucketName = "examplebucket";

    /* The full path of the object in OSS, excluding the bucket name. */
    std::string ObjectName = "exampledir/exampleobject.txt";

    /* The full local path for the downloaded file.
       If the file exists, it is overwritten. If it does not exist, it is created. */
    std::string DownloadFilePath = "D:\\localpath\\examplefile.txt";

    /* The directory for the checkpoint file.
       This directory must already exist. The checkpoint file records progress and
       is deleted automatically after the download completes. */
    std::string CheckpointFilePath = "D:\\localpath";

    /* Initialize network 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);

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

    if (!outcome.isSuccess()) {
        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;
}

Replace the following placeholders:

What's next

• For the complete sample code, see GitHub sample.

• For the underlying API operation, see GetObject.

• To create an OSSClient instance using custom domain names or Security Token Service (STS), see Create an OSSClient instance.