When you use the resumable upload feature to upload objects to Object Storage Service (OSS), you can specify a checkpoint file. The checkpoint file stores the information about the resumable upload task. If an object fails to be uploaded because of a network exception or program error, the upload task is resumed from the position recorded in the checkpoint file.
Prerequisites
A bucket is created. For more information, see Create buckets.Usage notes
- In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see Regions and endpoints.
- The
oss:PutObject
permission is required to perform resumable upload. For more information, see Attach a custom policy to a RAM user. - During resumable upload, the upload progress is recorded in a checkpoint file. If a part fails to be uploaded, the next upload starts from the position recorded in the checkpoint file. The checkpoint file is deleted after the resumable upload task is complete.
- The upload progress is recorded in the checkpoint file. Make sure that you have the write permissions on the checkpoint file.
- The checkpoint file contains a checksum. This checksum cannot be modified. If the checkpoint file is damaged, you must re-upload all parts of the object.
- If the local file is modified during the upload, you must re-upload all parts of the object.
Use OSS SDKs
The following code provides examples on how to perform resumable upload by using OSS SDKs for common programming languages. For more information about how to perform resumable upload by using OSS SDKs for other programming languages, see Overview.
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
public class Demo {
public static void main(String[] args) {
// In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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.
String accessKeyId = "yourAccessKeyId";
String accessKeySecret = "yourAccessKeySecret";
// Create an OSSClient instance.
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
try {
ObjectMetadata meta = new ObjectMetadata();
// Specify the type of content that you want to upload.
meta.setContentType("text/plain");
// Specify the access control list (ACL) of the object to upload.
// meta.setObjectAcl(CannedAccessControlList.Private);
// Configure parameters by using UploadFileRequest.
// Specify the name of the bucket such as examplebucket and the full path of the object such as exampledir/exampleobject.txt. The full path cannot contain the bucket name.
UploadFileRequest uploadFileRequest = new UploadFileRequest("examplebucket","exampledir/exampleobject.txt");
// Configure a single parameter by using UploadFileRequest.
// Specify the full path of the local file that you want to upload. Example: D:\\localpath\\examplefile.txt. By default, if you do not specify the path of the local file, the file is uploaded from the local path of the project to which the sample program belongs.
uploadFileRequest.setUploadFile("D:\\localpath\\examplefile.txt");
// Specify the number of concurrent upload threads for the resumable upload task. Default value: 1.
uploadFileRequest.setTaskNum(5);
// Specify the size of each part. Unit: bytes. Valid values: 100 KB to 5 GB. Default value: 100 KB.
uploadFileRequest.setPartSize(1 * 1024 * 1024);
// Specify whether to enable resumable upload. By default, resumable upload is disabled.
uploadFileRequest.setEnableCheckpoint(true);
// Specify the checkpoint file that records the upload result of each part. This file stores information about upload progress. If a part fails to be uploaded, the task can be continued based on the progress recorded in the checkpoint file. After the local file is uploaded, the checkpoint file is deleted.
// By default, if you do not specify this parameter, this checkpoint file shares the same directory as the object you want to upload. The directory is named ${uploadFile}.ucp.
uploadFileRequest.setCheckpointFile("yourCheckpointFile");
// Configure object metadata.
uploadFileRequest.setObjectMetadata(meta);
// Configure an upload callback. The parameter type is Callback.
//uploadFileRequest.setCallback("yourCallbackEvent");
// Start resumable upload.
ossClient.uploadFile(uploadFileRequest);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (Throwable ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
// Shut down the OSSClient instance.
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
const OSS = require('ali-oss');
const client = new OSS({
// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
region: 'yourregion',
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret'
// Set yourbucketname to the name of your bucket.
bucket: 'yourbucketname',
});
// Set yourfilepath to the local path of the uploaded object.
const filePath = "yourfilepath";
let checkpoint;
async function resumeUpload() {
// Set the number of upload retry operations to 5.
for (let i = 0; i < 5; i++) {
try {
const result = await client.multipartUpload('object-name', filePath, {
checkpoint,
async progress(percentage, cpt) {
checkpoint = cpt;
},
});
console.log(result);
break; // Break out of the loop.
} catch (e) {
console.log(e);
}
}
}
resumeUpload();
# -*- coding: utf-8 -*-
import oss2
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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.
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# 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.
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Set yourObjectName to the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt.
# Set yourLocalFile to the full path of the local file. Example: D:\\localpath\\examplefile.txt. By default, if you do not specify the path of the local file, the file is uploaded from the local path of the project to which the sample program belongs.
oss2.resumable_upload(bucket, 'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt')
# If you do not specify a directory by using the store parameter, the py-oss-upload directory is created in the HOME directory to store the checkpoint information.
# OSS SDK for Python 2.1.0 and later support the configuration of optional parameters in resumable upload. The following code provides an example on how to configure optional parameters in resumable upload:
# import sys
# # If the length of the data to upload cannot be determined, the value of total_bytes is None.
# def percentage(consumed_bytes, total_bytes):
# if total_bytes:
# rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
# print('\r{0}% '.format(rate), end='')
# sys.stdout.flush()
# If you use the store parameter to specify a directory, the checkpoint information is stored in the specified directory. If you use the num_threads parameter to specify the number of concurrent upload threads, make sure that the value of oss2.defaults.connection_pool_size is greater than or equal to the number of concurrent upload threads. The default number of concurrent threads is 1.
# oss2.resumable_upload(bucket, '<yourObjectName>', '<yourLocalFile>',
# store=oss2.ResumableStore(root='/tmp'),
# # Specify that multipart upload is used when the object size is greater than or equal to the value of multipart_threshold. The default value of multipart_threshold is 10 MB.
# multipart_threshold=100*1024,
# # Specify the size of each part. Unit: bytes. Valid values: 100 KB to 5 GB. Default value: 100 KB.
# part_size=100*1024,
# # Configure the function used to indicate the progress of the resumable upload task by implementing upload callback.
# progress_callback=percentage,
# # If you use the num_threads parameter to specify the number of concurrent upload threads, make sure that the value of oss2.defaults.connection_pool_size is greater than or equal to the number of concurrent upload threads. The default number of concurrent threads is 1.
# num_threads=4)
using Aliyun.OSS;
using Aliyun.OSS.Common;
// 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.
var endpoint = "yourEndpoint";
// The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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.
var accessKeyId = "yourAccessKeyId";
var accessKeySecret = "yourAccessKeySecret";
// Specify the name of the bucket. Example: examplebucket.
var bucketName = "examplebucket";
// Specify the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt.
var objectName = "exampledir/exampleobject.txt";
// Specify the full path of the local file. Example: D:\\localpath\\examplefile.txt.
// If you specify only the name of the local file such as examplefile.txt without specifying the local path, the local file is uploaded from the path of the project to which the sample program belongs.
var localFilename = "D:\\localpath\\examplefile.txt";
// Specify the checkpoint file. The file stores the progress information generated in the upload process.
string checkpointDir = "yourCheckpointDir";
// Create an OSSClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
// Configure parameters by using UploadFileRequest.
UploadObjectRequest request = new UploadObjectRequest(bucketName, objectName, localFilename)
{
// Specify the size of each part.
PartSize = 8 * 1024 * 1024,
// Specify the number of concurrent threads.
ParallelThreadCount = 3,
// Set the checkpointDir parameter to store the state of the resumable upload, which is used to resume the upload when the upload fails.
// If you set checkpointDir to null, resumable upload does not take effect and the object is uploaded again when it fails to be uploaded.
CheckpointDir = checkpointDir,
};
// Start resumable upload.
client.ResumableUploadObject(request);
Console.WriteLine("Resumable upload object:{0} succeeded", objectName);
}
catch (OssException ex)
{
Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
catch (Exception ex)
{
Console.WriteLine("Failed with error info: {0}", ex.Message);
}
// Specify the name of the bucket. Example: examplebucket.
String bucketName = "examplebucket";
// Specify the full path of the object. Example: exampledir/exampleobject.txt. The full path of the object cannot contain the bucket name.
String objectName = "exampledir/exampleobject.txt";
// Specify the full path of the local file. Example: /storage/emulated/0/oss/examplefile.txt.
String localFilepath = "/storage/emulated/0/oss/examplefile.txt";
String recordDirectory = Environment.getExternalStorageDirectory().getAbsolutePath() + "/oss_record/";
File recordDir = new File(recordDirectory);
// Make sure that the directory for the checkpoint file exists. If the directory does not exist, create a directory.
if (!recordDir.exists()) {
recordDir.mkdirs();
}
// Create a resumable upload request and specify the absolute path of the checkpoint file.
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// Set the DeleteUploadOnCancelling parameter to false when the OSSAsyncTask cancel() method is used. This ensures that the checkpoint file is retained. The object is uploaded from the position recorded in the checkpoint file during the next upload. If you do not specify this parameter, the default value true is used, which indicates that the checkpoint file is deleted. The entire object is uploaded again during the next upload.
request.setDeleteUploadOnCancelling(false);
// Configure an upload callback.
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
@Override
public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
ResumableUploadResult uploadResult = oss.resumableUpload(request);
package main
import (
"fmt"
"os"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func main() {
// Create an OSSClient instance.
// 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. Specify your actual endpoint.
// 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.
client, err := oss.New("yourEndpoint", "yourAccessKeyId", "yourAccessKeySecret")
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Specify the bucket name. Example: examplebucket.
bucket, err := client.Bucket("examplebucket")
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// Set the part size to 100 KB (100 × 1024), set the number of concurrent upload threads to 3, and enable resumable upload.
// Set yourObjectName to the full path of the object. The full path cannot contain the bucket name. Example: exampledir/exampleobject.txt.
// Set yourLocalFile to 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.
err = bucket.UploadFile("exampledir/exampleobject.txt", "D:\\localpath\\examplefile.txt", 100*1024, oss.Routines(3), oss.Checkpoint(true, ""))
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
}
// Obtain an upload ID to upload an object.
OSSResumableUploadRequest * resumableUpload = [OSSResumableUploadRequest new];
resumableUpload.bucketName = <bucketName>;
// objectKey is equivalent to objectName that indicates the complete path of the object you want to upload to OSS by using resumable upload. The path must include the extension of the object. For example, you can set objectKey to abc/efg/123.jpg.
resumableUpload.objectKey = <objectKey>;
resumableUpload.partSize = 1024 * 1024;
resumableUpload.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
};
NSString *cachesDir = [NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES) firstObject];
// Specify the path to store the checkpoint file.
resumableUpload.recordDirectoryPath = cachesDir;
// Set the deleteUploadOnCancelling parameter to NO. NO indicates that the checkpoint file is not deleted when the upload task fails. The next upload starts from the position recorded in the checkpoint file to upload the entire object. If you do not specify this parameter, default value YES is used. YES indicates that the checkpoint file is deleted when the upload task fails. The entire object is uploaded again during the next upload.
resumableUpload.deleteUploadIdOnCancelling = NO;
resumableUpload.uploadingFileURL = [NSURL fileURLWithPath:<your file path>];
OSSTask * resumeTask = [client resumableUpload:resumableUpload];
[resumeTask continueWithBlock:^id(OSSTask *task) {
if (task.error) {
NSLog(@"error: %@", task.error);
if ([task.error.domain isEqualToString:OSSClientErrorDomain] && task.error.code == OSSClientErrorCodeCannotResumeUpload) {
// The task cannot be resumed. You must obtain a new upload ID to upload the object.
}
} else {
NSLog(@"Upload file success");
}
return nil;
}];
// [resumeTask waitUntilFinished];
// [resumableUpload cancel];
#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;
}
#include "oss_api.h"
#include "aos_http_io.h"
/* 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. */
const char *endpoint = "yourEndpoint";
/* The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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. */
const char *access_key_id = "yourAccessKeyId";
const char *access_key_secret = "yourAccessKeySecret";
/* Specify the bucket name. Example: examplebucket. */
const char *bucket_name = "examplebucket";
/* Specify the full path of the object. The full path of the object cannot contain the bucket name. Example: exampledir/exampleobject.txt. */
const char *object_name = "exampledir/exampleobject.txt";
/* Specify the full path of the local file. */
const char *local_filename = "yourLocalFilename";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
/* Use a char* string to initialize the aos_string_t data type. */
aos_str_set(&options->config->endpoint, endpoint);
aos_str_set(&options->config->access_key_id, access_key_id);
aos_str_set(&options->config->access_key_secret, access_key_secret);
/* Specify whether to use CNAME. The value 0 indicates that CNAME is not used. */
options->config->is_cname = 0;
/* Configure network parameters such as the timeout period. */
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main(int argc, char *argv[])
{
/* Call the aos_http_io_initialize method in main() to initialize global resources such as networks and memory. */
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
exit(1);
}
/* Create a memory pool to manage memory. aos_pool_t is equivalent to apr_pool_t. The code used to create a memory pool is included in the APR library. */
aos_pool_t *pool;
/* Create a memory pool. The value of the second parameter is NULL. This parameter indicates that the pool does not inherit any other memory pools. */
aos_pool_create(&pool, NULL);
/* Create and initialize options. This parameter includes global configuration information such as endpoint, access_key_id, access_key_secret, is_cname, and curl. */
oss_request_options_t *oss_client_options;
/* Allocate the memory resources in the memory pool to the options. */
oss_client_options = oss_request_options_create(pool);
/* Initialize oss_client_options. */
init_options(oss_client_options);
/* Initialize the parameters. */
aos_string_t bucket;
aos_string_t object;
aos_string_t file;
aos_list_t resp_body;
aos_table_t *headers = NULL;
aos_table_t *resp_headers = NULL;
aos_status_t *resp_status = NULL;
oss_resumable_clt_params_t *clt_params;
aos_str_set(&bucket, bucket_name);
aos_str_set(&object, object_name);
aos_str_set(&file, local_filename);
aos_list_init(&resp_body);
/* Start resumable upload. */
clt_params = oss_create_resumable_clt_params_content(pool, 1024 * 100, 3, AOS_TRUE, NULL);
resp_status = oss_resumable_upload_file(oss_client_options, &bucket, &object, &file, headers, NULL, clt_params, NULL, &resp_headers, &resp_body);
if (aos_status_is_ok(resp_status)) {
printf("resumable upload succeeded\n");
} else {
printf("resumable upload failed\n");
}
/* Release the memory pool. This operation releases the memory resources allocated for the request. */
aos_pool_destroy(pool);
/* Release the allocated global resources. */
aos_http_io_deinitialize();
return 0;
}
require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
# In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint.
endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. 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.
access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
# Specify the name of the bucket. Example: examplebucket.
bucket = client.get_bucket('examplebucket')
# Replace my-object with the full path of the object. The full path cannot contain the bucket name.
# Replace local-file with the full path of the local file that you want to upload.
bucket.resumable_upload('my-object', 'local-file') do |p|
puts "Progress: #{p}"
end
bucket.resumable_upload(
'my-object', 'local-file',
:part_size => 100 * 1024, :cpt_file => '/tmp/x.cpt') { |p|
puts "Progress: #{p}"
}