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:GetObjectpermission. For more information, see Attach a custom policy to a RAM user.
Implementation method
You can use the OSSClient.ResumableDownloadObject method to implement resumable download. The following table describes the parameters that you can configure for DownloadObjectRequest.
Parameter | Description | Required | Default value | Method |
bucket | The name of the bucket. | Yes | None | Constructor |
key | The full path of the OSS object to download. | Yes | None | Constructor |
filePath | The full path of the local file to which the object is downloaded. | No | The name of the downloaded object | Constructor |
partSize | The size of each part. Valid values: 100 KB to 5 GB. | No | 8 MB | setPartSize |
threadNum | The number of parts that can be concurrently downloaded. | No | 3 | Constructor or setThreadNum |
checkpointDir | The path of the checkpoint file that records the results of the multipart download task. This parameter is required when you enable the resumable download feature. This file stores information about the download progress. If a part fails to be downloaded, the next download operation continues from the position recorded in the file. After the object is downloaded, the checkpoint file is deleted. | No | The directory in which the downloaded object is stored | Constructor or setCheckpointDir |
Sample code
The following code provides an example on how to perform resumable download:
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* Initialize information about the account that is used to access OSS. */
/* Specify 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 region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
std::string Region = "yourRegion";
/* Specify the name of the bucket. Example: examplebucket. */
std::string BucketName = "examplebucket";
/* Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt. */
std::string ObjectName = "exampledir/exampleobject.txt";
/* Download the object to the local path D:\\localpath as a local file named examplefile.txt. If a file that has the same name already exists in the specified path, the downloaded object overwrites the file. Otherwise, the downloaded object is saved in the path. */
/* If you do not specify the path of the local file, the downloaded object is saved to the path of the project to which the sample program belongs. */
std::string DownloadFilePath = "D:\\localpath\\examplefile.txt";
/* Specify the directory where the checkpoint file is stored and make sure that the specified directory exists, such as D:\\localpath. */
/* The checkpoint file is generated when the download is interrupted. If you want to resume the download task, you must specify the full path of the checkpoint file. After the object is downloaded, the checkpoint file is deleted. */
std::string CheckpointFilePath = "D:\\localpath";
/* Initialize resources such as network resources. */
InitializeSdk();
ClientConfiguration conf;
conf.signatureVersion = SignatureVersionType::V4;
/* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
client.SetRegion(Region);
/* Start 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 resources such as network resources. */
ShutdownSdk();
return 0;
}