在上傳大文件(超過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}"
}
文檔內容是否對您有幫助?