在上传大文件（超过5 GB）到OSS的过程中，如果出现网络中断、程序异常退出等问题导致文件上传失败，甚至重试多次仍无法完成上传，您需要使用断点续传上传的方式。断点续传上传将需要上传的大文件分成多个较小的分片并发上传，加速上传完成时间。如果上传过程中，某一分片上传失败，再次上传时会从Checkpoint文件记录的断点继续上传，无需重新上传所有分片。上传完成后，所有分片将合并成完整的文件。
前提条件
已创建存储空间（Bucket）。详情请参见控制台创建存储空间。注意事项
本文以华东1（杭州）外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见访问域名和数据中心。
要断点续传上传，您必须有
oss:PutObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。SDK会将上传的状态信息记录在Checkpoint文件中，所以要确保程序对Checkpoint文件有写权限。
请勿修改Checkpoint文件中携带的校验信息。如果Checkpoint文件损坏，则会重新上传所有分片。
如果上传过程中本地文件发生了改变，则会重新上传所有分片。
使用阿里云SDK
以下仅列举常见SDK的断点续传上传的代码示例。关于其他SDK的断点续传上传的代码示例，请参见SDK简介。
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
public class Demo {
public static void main(String[] args) {
// Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
try {
ObjectMetadata meta = new ObjectMetadata();
// 指定上传的内容类型。
meta.setContentType("text/plain");
// 文件上传时设置访问权限ACL。
// meta.setObjectAcl(CannedAccessControlList.Private);
// 通过UploadFileRequest设置多个参数。
// 依次填写Bucket名称（例如examplebucket）以及Object完整路径（例如exampledir/exampleobject.txt），Object完整路径中不能包含Bucket名称。
UploadFileRequest uploadFileRequest = new UploadFileRequest("examplebucket","exampledir/exampleobject.txt");
// 通过UploadFileRequest设置单个参数。
// 填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。
uploadFileRequest.setUploadFile("D:\\localpath\\examplefile.txt");
// 指定上传并发线程数，默认值为1。
uploadFileRequest.setTaskNum(5);
// 指定上传的分片大小，单位为字节，取值范围为100 KB~5 GB。默认值为100 KB。
uploadFileRequest.setPartSize(1 * 1024 * 1024);
// 开启断点续传，默认关闭。
uploadFileRequest.setEnableCheckpoint(true);
// 记录本地分片上传结果的文件。上传过程中的进度信息会保存在该文件中，如果某一分片上传失败，再次上传时会根据文件中记录的点继续上传。上传完成后，该文件会被删除。
// 如果未设置该值，默认与待上传的本地文件同路径，名称为${uploadFile}.ucp。
uploadFileRequest.setCheckpointFile("yourCheckpointFile");
// 文件的元数据。
uploadFileRequest.setObjectMetadata(meta);
// 设置上传回调，参数为Callback类型。
//uploadFileRequest.setCallback("yourCallbackEvent");
// 断点续传上传。
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 {
// 关闭OSSClient。
if (ossClient != null) {
ossClient.shutdown();
}
}
}
} const OSS = require('ali-oss')
const client = new OSS({
// yourregion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
region: 'yourregion',
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
accessKeyId: process.env.OSS_ACCESS_KEY_ID,
accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
// 填写Bucket名称。
bucket: 'examplebucket'
});
// yourfilepath填写已上传文件所在的本地路径。
const filePath = "yourfilepath";
let checkpoint;
async function resumeUpload() {
// 重试五次。
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; // 跳出当前循环。
} catch (e) {
console.log(e);
}
}
}
resumeUpload();# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称，例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# yourObjectName填写Object完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。
# yourLocalFile填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。
oss2.resumable_upload(bucket, 'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt')
# 如未使用参数store指定目录，则会在HOME目录下建立.py-oss-upload目录来保存断点信息。
# Python SDK 2.1.0以上版本支持断点续传上传时设置以下可选参数。
# import sys
# # 当无法确定待上传的数据长度时，total_bytes的值为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()
# # 如果使用store指定了目录，则断点信息将保存在指定目录中。如果使用num_threads设置并发上传线程数，请将oss2.defaults.connection_pool_size设置为大于或等于并发上传线程数。默认并发上传线程数为1。
# oss2.resumable_upload(bucket, '<yourObjectName>', '<yourLocalFile>',
# store=oss2.ResumableStore(root='/tmp'),
# # 指定当文件长度大于或等于可选参数multipart_threshold（默认值为10 MB）时，则使用分片上传。
# multipart_threshold=100*1024,
# # 设置分片大小，单位为字节，取值范围为100 KB~5 GB。默认值为100 KB。
# part_size=100*1024,
# # 设置上传回调进度函数。
# progress_callback=percentage,
# # 如果使用num_threads设置并发上传线程数，请将oss2.defaults.connection_pool_size设置为大于或等于并发上传线程数。默认并发上传线程数为1。
# num_threads=4)using Aliyun.OSS;
using Aliyun.OSS.Common;
// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称，例如examplebucket。
var bucketName = "examplebucket";
// 填写Object完整路径，Object完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。
var objectName = "exampledir/exampleobject.txt";
// 填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。
// 如果未指定本地路径只填写了文件名称（例如examplefile.txt），则默认从示例程序所属项目对应本地路径中上传文件。
var localFilename = "D:\\localpath\\examplefile.txt";
// 记录本地分片上传结果的文件。上传过程中的进度信息会保存在该文件中。
string checkpointDir = "yourCheckpointDir";
// 创建OssClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
// 通过UploadFileRequest设置多个参数。
UploadObjectRequest request = new UploadObjectRequest(bucketName, objectName, localFilename)
{
// 指定上传的分片大小。
PartSize = 8 * 1024 * 1024,
// 指定并发线程数。
ParallelThreadCount = 3,
// checkpointDir保存断点续传的中间状态，用于失败后继续上传。
// 如果checkpointDir为null，断点续传功能不会生效，每次失败后都会重新上传。
CheckpointDir = checkpointDir,
};
// 断点续传上传。
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);
}// 填写Bucket名称，例如examplebucket。
String bucketName = "examplebucket";
// 填写Object完整路径，例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
String objectName = "exampledir/exampleobject.txt";
// 填写文件完整路径，例如/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);
// 确保断点记录的保存文件夹已存在，如果不存在则新建断点记录的保存文件夹。
if (!recordDir.exists()) {
recordDir.mkdirs();
}
// 创建断点续传上传请求，并指定断点记录文件的保存路径，保存路径为断点记录文件的绝对路径。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// 调用OSSAsyncTask cancel()方法时，设置DeleteUploadOnCancelling为false，表示不删除断点记录文件，下次再上传同一个文件时将从断点记录处继续上传。如果不设置此参数，则默认值为true，表示删除断点记录文件，下次再上传同一个文件时则重新上传。
request.setDeleteUploadOnCancelling(false);
// 设置上传回调。
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() {
// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 创建OSSClient实例。
// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 填写Bucket名称，例如examplebucket。
bucket, err := client.Bucket("examplebucket")
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 通过UploadFile实现断点续传上传时，限制分片数量不能超过10000。
// 您需要结合上传文件的大小，合理设置每个分片的大小。每个分片大小的取值范围为100 KB~5 GB。默认值为100 KB（即100*1024）。
// 通过oss.Routines指定分片上传并发数为3。
// yourObjectName填写Object完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。
// yourLocalFile填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。
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)
}
} // 获取UploadId上传文件。
OSSResumableUploadRequest * resumableUpload = [OSSResumableUploadRequest new];
resumableUpload.bucketName = <bucketName>;
// objectKey等同于objectName，表示断点上传文件到OSS时需要指定包含文件后缀在内的完整路径，例如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];
// 设置断点记录保存路径。
resumableUpload.recordDirectoryPath = cachesDir;
// 将参数deleteUploadIdOnCancelling设置为NO，表示不删除断点记录文件，上传失败后将从断点记录处继续上传直到文件上传完成。如果不设置此参数，即保留默认值YES，表示删除断点记录文件，下次再上传同一文件时则重新上传。
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) {
// 此任务无法续传，需获取新的uploadId重新上传。
}
} else {
NSLog(@"Upload file success");
}
return nil;
}];
// [resumeTask waitUntilFinished];
// [resumableUpload cancel];
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;
int main(void)
{
/* 初始化OSS账号信息。*/
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
std::string Endpoint = "yourEndpoint";
/* 填写Bucket名称，例如examplebucket。*/
std::string BucketName = "examplebucket";
/* 填写Object的完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。*/
std::string ObjectName = "exampledir/exampleobject.txt";
/* 填写本地文件的完整路径，例如D:\\localpath\\examplefile.txt。如果未指定本地路径，则默认从示例程序所属项目对应本地路径中上传文件。*/
std::string UploadFilePath = "D:\\localpath\\examplefile.txt";
/* 记录本地分片上传结果的文件。上传过程中的进度信息会保存在该文件中，如果某一分片上传失败，再次上传时会根据文件中记录的断点继续上传。上传完成后，该文件会被删除。*/
/* 设置断点记录文件所在的目录，并确保指定的目录已存在，例如D:\\local。如果未设置该值，默认与待上传的本地文件同路径。*/
std::string CheckpointFilePath = "D:\\local";
/* 初始化网络等资源。*/
InitializeSdk();
ClientConfiguration conf;
/* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
OssClient client(Endpoint, credentialsProvider, conf);
/* 断点续传上传。*/
UploadObjectRequest request(BucketName, ObjectName, UploadFilePath, CheckpointFilePath);
auto outcome = client.ResumableUploadObject(request);
if (!outcome.isSuccess()) {
/* 异常处理。*/
std::cout << "ResumableUploadObject fail" <<
",code:" << outcome.error().Code() <<
",message:" << outcome.error().Message() <<
",requestId:" << outcome.error().RequestId() << std::endl;
return -1;
}
/* 释放网络等资源。*/
ShutdownSdk();
return 0;
}#include "oss_api.h"
#include "aos_http_io.h"
/* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
const char *endpoint = "yourEndpoint";
/* 填写Bucket名称，例如examplebucket。*/
const char *bucket_name = "examplebucket";
/* 填写Object完整路径，完整路径中不能包含Bucket名称，例如exampledir/exampleobject.txt。*/
const char *object_name = "exampledir/exampleobject.txt";
/* 填写本地文件的完整路径。*/
const char *local_filename = "yourLocalFilename";
void init_options(oss_request_options_t *options)
{
options->config = oss_config_create(options->pool);
/* 用char*类型的字符串初始化aos_string_t类型。*/
aos_str_set(&options->config->endpoint, endpoint);
/* 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
aos_str_set(&options->config->access_key_id, getenv("OSS_ACCESS_KEY_ID"));
aos_str_set(&options->config->access_key_secret, getenv("OSS_ACCESS_KEY_SECRET"));
/* 是否使用了CNAME。0表示不使用。*/
options->config->is_cname = 0;
/* 设置网络相关参数，比如超时时间等。*/
options->ctl = aos_http_controller_create(options->pool, 0);
}
int main(int argc, char *argv[])
{
/* 在程序入口调用aos_http_io_initialize方法来初始化网络、内存等全局资源。*/
if (aos_http_io_initialize(NULL, 0) != AOSE_OK) {
exit(1);
}
/* 用于内存管理的内存池（pool），等价于apr_pool_t。其实现代码在apr库中。*/
aos_pool_t *pool;
/* 重新创建一个新的内存池，第二个参数是NULL，表示没有继承其它内存池。*/
aos_pool_create(&pool, NULL);
/* 创建并初始化options，该参数包括endpoint、access_key_id、acces_key_secret、is_cname、curl等全局配置信息。*/
oss_request_options_t *oss_client_options;
/* 在内存池中分配内存给options。*/
oss_client_options = oss_request_options_create(pool);
/* 初始化Client的选项oss_client_options。*/
init_options(oss_client_options);
/* 初始化参数。*/
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);
/* 断点续传。*/
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");
}
/* 释放内存池，相当于释放了请求过程中各资源分配的内存。*/
aos_pool_destroy(pool);
/* 释放之前分配的全局资源。*/
aos_http_io_deinitialize();
return 0;
}require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
# Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
access_key_id: ENV['OSS_ACCESS_KEY_ID'],
access_key_secret: ENV['OSS_ACCESS_KEY_SECRET']
)
# 填写Bucket名称，例如examplebucket。
bucket = client.get_bucket('examplebucket')
# key填写Object完整路径，Object完整路径中不能包含Bucket名称，例如exampledir/example.zip。
# file填写本地文件的完整路径，例如/tmp/example.zip。
bucket.resumable_upload('exampledir/example.zip', '/tmp/example.zip') do |p|
puts "Progress: #{p}"
end
bucket.resumable_upload(
'exampledir/example.zip', '/tmp/example.zip',
:part_size => 100 * 1024, :cpt_file => '/tmp/example.zip.cpt') { |p|
puts "Progress: #{p}"
}