Android斷點續(xù)傳上傳
更新時間：
在無線網(wǎng)絡(luò)下，上傳較大的文件持續(xù)時間長，可能會遇到因為網(wǎng)絡(luò)條件差、用戶切換網(wǎng)絡(luò)等原因?qū)е律蟼髦型臼?，整個文件需要重新上傳。為此，Android SDK提供了斷點續(xù)傳上傳功能。
使用說明
Android SDK提供了resumableUpload以及sequenceUpload兩種方法用于斷點續(xù)傳上傳。
（推薦）resumableUpload表示并發(fā)上傳分片，即同時支持最多5個分片并發(fā)上傳。
sequenceUpload表示順序上傳分片，即上一個分片上傳完成后開始上傳下一個分片。
以下示例代碼僅提供通過resumableUpload的方法斷點續(xù)傳上傳。如果您希望通過斷點續(xù)傳的方式上傳多個文件或視頻，需創(chuàng)建多個ResumableUploadRequest。
注意事項
使用本文示例前您需要先通過自定義域名、STS等方式新建OSSClient，具體請參見如何初始化Android端OSSClient實例。
對于移動端而言，如果不是大文件（例如小于5 GB的文件），不建議使用斷點續(xù)傳的方式上傳。斷點續(xù)傳上傳是通過分片上傳實現(xiàn)的，上傳單個文件需要進行多次網(wǎng)絡(luò)請求，效率不高。對于通過斷點續(xù)傳的方式上傳大于5 GB的文件時：
斷點續(xù)傳上傳前
通過斷點續(xù)傳上傳的方式將文件上傳到OSS前，您可以指定斷點記錄的保存文件夾。斷點續(xù)傳上傳僅在本次上傳生效。
如果未指定斷點記錄的保存文件夾，假設(shè)某個分片因為網(wǎng)絡(luò)原因等導(dǎo)致文件上傳失敗時，將耗用大量的重試時間及流量來重新上傳整個大文件。
如果指定了斷點記錄的保存文件夾，在文件上傳失敗時，將從斷點記錄處繼續(xù)上傳未上傳完成的部分。
斷點續(xù)傳上傳時
斷點續(xù)傳上傳僅支持上傳本地文件。斷點續(xù)傳上傳支持上傳回調(diào)，使用方法與常見的上傳回調(diào)類似。具體操作，請參見Callback。
斷點續(xù)傳上傳依賴InitMultipartUpload、UploadPart、ListParts、CompleteMultipartUpload、AbortMultipartUpload等接口來實現(xiàn)。如果您需要通過STS鑒權(quán)模式來使用斷點續(xù)傳上傳，則需要保證您擁有訪問以上API接口的權(quán)限。
斷點續(xù)傳上傳默認已開啟每個分片上傳時的MD5校驗，因此無需在請求中設(shè)置
Content-Md5頭部。如果同一任務(wù)一直未完成續(xù)傳，可能會在OSS上積累無用的碎片。此時，您可以為Bucket設(shè)置生命周期規(guī)則來定時清理碎片。具體操作，請參見生命周期管理。
示例代碼
您可以通過同步或者異步方式斷點續(xù)傳上傳本地文件到OSS。
以下代碼以同步的方式斷點續(xù)傳上傳examplefile.txt文件到目標(biāo)存儲空間examplebucket中exampledir目錄下的exampleobject.txt文件，并將斷點記錄文件保存到本地。
// 填寫B(tài)ucket名稱，例如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();
}
// 創(chuàng)建斷點續(xù)傳上傳請求，并指定斷點記錄文件的保存路徑，保存路徑為斷點記錄文件的絕對路徑。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// 調(diào)用OSSAsyncTask cancel()方法時，設(shè)置DeleteUploadOnCancelling為false，表示不刪除斷點記錄文件，下次再上傳同一個文件時將從斷點記錄處繼續(xù)上傳。如果不設(shè)置此參數(shù)，則默認值為true，表示刪除斷點記錄文件，下次再上傳同一個文件時則重新上傳。
request.setDeleteUploadOnCancelling(false);
// 設(shè)置上傳回調(diào)。
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);對于Android10及之后版本的分區(qū)存儲，您可以使用文件的Uri上傳文件到OSS。
// 填寫B(tài)ucket名稱，例如examplebucket。
String bucketName = "examplebucket";
// 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
String objectName = "exampledir/exampleobject.txt";
String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";
File recordDir = new File(recordDirectory);
// 確保斷點記錄的保存文件夾已存在，如果不存在則新建斷點記錄的保存文件夾。
if (!recordDir.exists()) {
recordDir.mkdirs();
}
// 創(chuàng)建斷點續(xù)傳上傳請求，并指定斷點記錄文件的保存路徑，保存路徑為斷點記錄文件的絕對路徑。
// 這里參數(shù)"fileUri"需要填入文件的實際Uri值。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// 調(diào)用OSSAsyncTask cancel()方法時，設(shè)置DeleteUploadOnCancelling為false，表示不刪除斷點記錄文件，下次再上傳同一個文件時將從斷點記錄處繼續(xù)上傳。如果不設(shè)置此參數(shù)，則默認值為true，表示刪除斷點記錄文件，下次再上傳同一個文件時則重新上傳。
request.setDeleteUploadOnCancelling(false);
// 設(shè)置上傳回調(diào)。
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);如果在斷點續(xù)傳上傳時無需將斷點記錄文件保存到本地，示例代碼如下：
// 填寫B(tài)ucket名稱，例如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";
// 創(chuàng)建斷點續(xù)傳上傳請求。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);
// 設(shè)置上傳回調(diào)。
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);以下代碼以異步的方式斷點續(xù)傳上傳examplefile.txt文件到目標(biāo)存儲空間examplebucket中exampledir目錄下的exampleobject.txt文件，并將斷點記錄文件保存到本地。
// 填寫B(tài)ucket名稱，例如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();
}
// 創(chuàng)建斷點上傳請求，并指定斷點記錄文件的保存路徑，保存路徑為斷點記錄文件的絕對路徑。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath, recordDirectory);
// 調(diào)用OSSAsyncTask cancel()方法時，設(shè)置DeleteUploadOnCancelling為false，表示不刪除斷點記錄文件，下次再上傳同一個文件時將從斷點記錄處繼續(xù)上傳。如果不設(shè)置此參數(shù)，則默認值為true，表示刪除斷點記錄文件，下次再上傳同一個文件時則重新上傳。
request.setDeleteUploadOnCancelling(false);
// 設(shè)置上傳過程回調(diào)。
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
@Override
public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
@Override
public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
Log.d("resumableUpload", "success!");
}
@Override
public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
// 異常處理。
}
});
// 等待完成斷點上傳任務(wù)。
resumableTask.waitUntilFinished(); 對于Android10及之后版本的分區(qū)存儲，您可以使用文件的Uri上傳文件到OSS。
// 填寫B(tài)ucket名稱，例如examplebucket。
String bucketName = "examplebucket";
// 填寫Object完整路徑，例如exampledir/exampleobject.txt。Object完整路徑中不能包含Bucket名稱。
String objectName = "exampledir/exampleobject.txt";
String recordDirectory = getApplication().getFilesDir().getAbsolutePath() + "/oss_record/";
File recordDir = new File(recordDirectory);
// 確保斷點記錄的保存文件夾已存在，如果不存在則新建斷點記錄的保存文件夾。
if (!recordDir.exists()) {
recordDir.mkdirs();
}
// 創(chuàng)建斷點續(xù)傳上傳請求，并指定斷點記錄文件的保存路徑，保存路徑為斷點記錄文件的絕對路徑。
// 這里參數(shù)"fileUri"需要填入文件的實際Uri值。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, fileUri, recordDirectory);
// 調(diào)用OSSAsyncTask cancel()方法時，設(shè)置DeleteUploadOnCancelling為false時，表示不刪除斷點記錄文件，下次再上傳同一個文件時將從斷點記錄處繼續(xù)上傳。如果不設(shè)置此參數(shù)，則默認值為true，表示刪除斷點記錄文件，下次再上傳同一個文件時則重新上傳。
request.setDeleteUploadOnCancelling(false);
// 設(shè)置上傳回調(diào)。
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
@Override
public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
@Override
public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
Log.d("resumableUpload", "success!");
}
@Override
public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
// 異常處理。
}
});
// 等待完成斷點上傳任務(wù)。
resumableTask.waitUntilFinished();如果在斷點續(xù)傳上傳時無需將斷點記錄文件保存到本地，示例代碼如下：
// 填寫B(tài)ucket名稱，例如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";
// 創(chuàng)建斷點上傳請求。
ResumableUploadRequest request = new ResumableUploadRequest(bucketName, objectName, localFilepath);
// 設(shè)置上傳過程回調(diào)。
request.setProgressCallback(new OSSProgressCallback<ResumableUploadRequest>() {
@Override
public void onProgress(ResumableUploadRequest request, long currentSize, long totalSize) {
Log.d("resumableUpload", "currentSize: " + currentSize + " totalSize: " + totalSize);
}
});
// 異步調(diào)用斷點上傳。
OSSAsyncTask resumableTask = oss.asyncResumableUpload(request, new OSSCompletedCallback<ResumableUploadRequest, ResumableUploadResult>() {
@Override
public void onSuccess(ResumableUploadRequest request, ResumableUploadResult result) {
Log.d("resumableUpload", "success!");
}
@Override
public void onFailure(ResumableUploadRequest request, ClientException clientExcepion, ServiceException serviceException) {
// 異常處理。
}
});
// 等待完成斷點上傳任務(wù)。
resumableTask.waitUntilFinished(); 相關(guān)文檔
關(guān)于Bucket設(shè)置生命周期規(guī)則，請參見生命周期管理。
關(guān)于斷點續(xù)傳上傳支持上傳回調(diào)使用方法，請參見Callback。
關(guān)于初始化OSSClient，請參見如何初始化Android端OSSClient實例。
文檔內(nèi)容是否對您有幫助？