文件上傳是指將媒體文件(本地文件或網絡文件)從客戶端上傳至點播存儲。在Android端上,文件上傳通過上傳實例(VODUploadClient)完成。視頻上傳成功后會返回videoId作為視頻ID,用戶需要通過拿到videoId自行獲取播放地址進行播放。本文介紹如何使用Android端上傳SDK完成媒體文件上傳。
前提條件
您已集成Android端上傳SDK。詳情請參見集成Android端上傳SDK。
上傳流程
客戶端上傳SDK封裝了OSS上傳邏輯。在客戶端上傳媒體文件時,會直接將文件上傳到點播存儲(基于OSS),不會再經服務端進行中轉,故客戶端上傳必須進行鑒權,也就是需要您在應用服務器上部署授權服務以獲取上傳地址和憑證。目前客戶端上傳SDK支持兩種授權方式,兩種方式差異對比請參見憑證方式與STS方式對比,推薦使用憑證方式。
上傳地址和憑證方式上傳流程詳解
以集成點播服務端SDK獲取上傳地址和憑證為例,完整的上傳流程如下圖所示:
用戶在上傳應用服務器上部署授權服務(如集成點播服務端SDK)用于獲取上傳地址和憑證。
客戶端向上傳應用服務器發起請求獲取上傳地址和憑證。
上傳應用服務器向視頻點播服務發起請求獲取上傳地址和憑證。
點播服務返回上傳地址和憑證。
說明點播服務在下發上傳地址和憑證時還會自動創建媒資信息,即媒體ID(MediaId),用于媒資生命周期管理或媒體處理。
獲取音視頻上傳地址和憑證返回的
VideoId
即媒體ID。獲取圖片上傳地址和憑證返回的
ImageId
即媒體ID。獲取輔助媒資上傳地址和憑證返回的
MediaId
即媒體ID。請妥善保存媒體ID,作為媒資管理、音視頻播放、媒體處理等的輸入。
上傳應用服務器向客戶端下發上傳地址和憑證。
說明下發地址和憑證即可,無需Base64解碼。
客戶端使用上傳地址和憑證初始化上傳實例。
客戶端構造上傳參數發起上傳請求。
OSS服務返回上傳結果。
說明上傳結果也可以通過提前配置回調接收上傳相關事件來監聽。
STS方式上傳流程詳解
如需使用STS臨時授權方式(阿里云Security Token Service)訪問點播服務,請為RAM用戶創建角色并授予角色VOD相關權限。操作指引請參見使用STS臨時授權方案上傳視頻。
使用STS方式上傳的完整的流程如下圖所示:
用戶在上傳應用服務器上部署授權服務(如集成阿里云STS SDK)用于獲取STS臨時Token。
客戶端向上傳應用服務器發起請求獲取STS臨時Token。
上傳應用服務器向阿里云STS服務發起請求獲取STS臨時Token。
阿里云STS服務返回上傳地址和憑證。
上傳應用服務器向客戶端下發STS臨時Token。
客戶端使用STS臨時Token初始化上傳實例。
客戶端構造請求發起上傳請求。
OSS服務返回上傳結果。
說明上傳結果也可以通過提前配置回調接收上傳相關事件來監聽。
上傳文件
在Android端上傳文件的基本操作步驟如下:
獲取上傳地址和憑證或STS臨時Token,用于上傳授權。
使用上傳憑證或STS臨時Token初始化上傳實例。
設置回調,用于接收上傳過程中關鍵節點的消息。
根據上傳的文件類型(音視頻或圖片)構造上傳參數。
開始上傳。
音視頻和圖片的上傳參數略有差異。目前客戶端不支持上傳輔助媒資。
步驟一、獲取上傳授權
點播客戶端上傳SDK支持兩種授權方式,分別是憑證方式和STS方式。關于兩種方式的適用場景請參見憑證方式與STS方式對比。
(推薦)部署授權服務獲取上傳地址和憑證的操作指引請參見使用上傳地址和憑證方式上傳。
部署STS服務獲取STS臨時Token的操作指引請參見使用STS方式上傳。
?執行結果
用獲取到的上傳地址和憑證或STS臨時Token作為入參初始化上傳實例。
步驟二、初始化上傳實例
請根據業務需求選擇用上傳地址和憑證方式或STS方式初始化上傳實例。
(推薦)方式一:上傳地址和憑證方式初始化上傳實例
1.聲明上傳實例(VODUploadClient
)初始化回調。
uploader = new VODUploadClientImpl(getApplicationContext());
2.初始化上傳實例(VODUploadClient
)。
上傳地址和憑證方式調用
init
方法初始化。在上傳開始后觸發的
onUploadStarted
回調中調用setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress)
方法設置上傳地址和憑證。音視頻上傳場景下,如果上傳地址和憑證過期,會觸發
onUploadTokenExpired
回調,需要調用resumeWithAuth(uploadAuth)
方法,設置新的上傳憑證繼續上傳。
// create VODUploadClient
final VODUploadClient uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
VODUploadCallback callback = new VODUploadCallback(){
@Override
public void onUploadSucceed(UploadFileInfo info) {
OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
}
@Override
public void onUploadFailed(UploadFileInfo info, String code, String message) {
OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
}
@Override
public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
}
@Override
public void onUploadTokenExpired() {
OSSLog.logError("onExpired ------------- ");
//重新刷新上傳憑證:RefreshUploadVideo。
uploadAuth = "此處需要設置重新刷新憑證之后的值";
uploader.resumeWithAuth(uploadAuth);
}
@Override
public void onUploadRetry(String code, String message) {
OSSLog.logError("onUploadRetry ------------- ");
}
@Override
public void onUploadRetryResume() {
OSSLog.logError("onUploadRetryResume ------------- ");
}
@Override
public void onUploadStarted(UploadFileInfo uploadFileInfo) {
OSSLog.logError("onUploadStarted ------------- ");
//uploadAuth及uploadAddress即為上傳憑證和地址。
uploader.setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress);
}
};
//上傳初始化
uploader.init(callback);
方式二:STS方式初始化上傳實例
1.聲明上傳實例(VODUploadClient
)初始化回調。
uploader = new VODUploadClientImpl(getApplicationContext());
2.初始化上傳實例(VODUploadClient
)。
STS方式調用
init(accessKeyId, accessKeySecret, secretToken, expireTime, callback)
方法初始化,初始化參數secretToken是請求獲取的臨時STS憑證。
當STS臨時憑證過期時,觸發
OnUploadTokenExpired
回調,需要調用resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime)
方法,設置新的STS繼續上傳。
// create VODUploadClient object
uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
// setup callback
VODUploadCallback callback = new VODUploadCallback() {
public void onUploadSucceed(UploadFileInfo info) {
OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
}
public void onUploadFailed(UploadFileInfo info, String code, String message) {
OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
}
public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
}
}
}
public void onUploadTokenExpired() {
OSSLog.logError("onExpired ------------- ");
//重新獲取STS之后調用resumeWithToken
uploader.resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime);
}
public void onUploadRetry(String code, String message) {
OSSLog.logError("onUploadRetry ------------- ");
}
public void onUploadRetryResume() {
OSSLog.logError("onUploadRetryResume ------------- ");
}
public void onUploadStarted(UploadFileInfo uploadFileInfo) {
OSSLog.logError("onUploadStarted ------------- ");
}
};
//初始化,臨時賬號過期時,在onUploadTokenExpired事件中,用resumeWithToken更新臨時賬號,上傳默認支持斷點續傳
uploader.init(accessKeyId, accessKeySecret, secretToken, expireTime, callback);
步驟三、設置上傳狀態回調類
設置VODUploadCallback對象,該對象是上傳狀態的回調類。需要設置下列回調方法:
/**
上傳完成回調
@param info 上傳文件信息
*/
void onUploadSucceed(UploadFileInfo info);
/**
上傳失敗回調
@param info 上傳文件信息
@param code 錯誤碼
@param message 錯誤描述
*/
void onUploadFailed(UploadFileInfo info, String code, String message);
/**
上傳進度回調
@param fileInfo 上傳文件信息
@param uploadedSize 已上傳大小
@param totalSize 總大小
*/
void onUploadProgress(UploadFileInfo fileInfo, long uploadedSize, long totalSize);
/**
上傳地址和憑證過期回調
上傳地址和憑證方式上傳需要調用resumeWithAuth方法繼續上傳
STS方式上傳需要調用resumeWithToken方法繼續上傳
*/
void onUploadTokenExpired();
/**
上傳開始重試回調
*/
void onUploadRetry(String code, String message);
/**
上傳結束重試,繼續上傳回調
*/
void onUploadRetryResume ();
/**
開始上傳回調
上傳地址和憑證方式上傳需要調用setUploadAuthAndAddress:uploadAuth:uploadAddress:方法設置上傳地址和憑證
@param fileInfo 上傳文件信息
*/
void onUploadStarted(UploadFileInfo fileInfo);
步驟四、構造上傳請求函數
音視頻文件參數
構造添加音視頻文件到上傳列表的上傳請求函數。
String filePath = "文件地址";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("標題" + index);
vodInfo.setDesc("描述." + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);
圖片文件參數
構造添加圖片文件到上傳列表的上傳請求函數。
String filePath = “圖片文件地址”;
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle(“標題” + index);
vodInfo.setDesc(“描述.” + index);
vodInfo.cateId (19);
vodInfo.tags(“sports”);
uploader.addFile(filePath,vodInfo);
vodInfo說明
//標題
String title;
//標簽
List tags;
//描述
String desc;
//分類
idInteger cateId;
//封面url(完整的URL https://)
String coverUrl;
添加文件后,SDK會將待上傳文件封裝為UploadFileInfo
對象,具體結構如下:
//文件本地路徑
String filePath;
//endpoint
String endpoint;
//bucket
String bucket;
//object
String object;
//VodInfo
VodInfo vodInfo;
步驟五、開始上傳
調用
start()
方法開始上傳。void start();
該方法調用后,會觸發
onUploadStarted
回調。如果通過上傳地址和憑證方式上傳,需要在該回調方法中設置上傳地址和憑證。示例代碼如下:void setUploadAuthAndAddress(UploadFileInfo uploadFileInfo, String uploadAuth, String uploadAddress)
文件開始上傳后,
onUploadProgress
回調開始同步上傳進度。文件上傳成功后,
onUploadSucceed
回調會返回上傳結果。回調包含上傳結果的videoId
和imageUrl
屬性。
?執行結果
高級功能
隊列管理
上傳實例(VODUploadClient
)支持添加多個文件順序上傳,并提供了以下方法管理上傳隊列:
盡管VODUploadClient支持多文件上傳,如果使用上傳憑證和上傳地址方式上傳,每個文件還是需要單獨設置。基于多文件上傳代碼復雜度的考慮,建議只添加單文件上傳。
從隊列中刪除上傳文件。如果待刪除的文件正在上傳中,則取消上傳并自動上傳下一個文件。
void deleteFile(int index)
清空上傳隊列。如果有文件在上傳,則取消上傳。
void clearFiles()
獲取上傳文件隊列。
List<UploadFileInfo> listFiles()
將文件標記為取消,文件仍保留在上傳列表中。如果待取消的文件正在上傳中,則取消上傳并自動上傳下一個文件。
cancelFile(int index)
恢復已取消上傳的文件,并自動開始上傳。
resumeFile(int index)
上傳控制
上傳實例(VODUploadClient
)支持以下上傳控制方法:
停止上傳。如果有文件正在上傳中,則取消上傳。
void stop();
說明停止上傳后如需恢復上傳,請調用
resumeFile
恢復待上傳文件,或者清空隊列后重新添加文件上傳。暫停上傳。
void pause();
恢復上傳。
void resume();
回調處理
上傳實例(VODUploadClient
)支持以下回調:
上傳失敗
上傳失敗時,會觸發
onUploadFailed
回調。在該回調方法中,可以通過code
和message
查看具體原因,并在頁面上提示。更多錯誤碼信息,請參見錯誤碼表和OSS錯誤碼。上傳地址和憑證過期
上傳憑證過期,會觸發
onUploadTokenExpired
回調。在該回調方法中,可以向AppServer重新請求新的上傳憑證,并調用以下方法繼續上傳。說明需要在回調中設置刷新后的上傳憑證。
上傳超時
上傳超時,會觸發
uploadRetry
回調并自動重試。在該回調方法中,可以在頁面上給予提示或者調用cancel
方法停止上傳。此外,可以設置maxRetryCount
屬性,指定最大重試次數。超時重試可以繼續上傳時,會觸發uploadRetryResume
回調并恢復上傳。
超時處理
上傳實例(VODUploadClient
)支持設置最大超時次數:
/**
配置最大超時重試次數,默認值INT_MAX,超時時間
*/
void setVodHttpClientConfig(VodHttpClientConfig var);
分片上傳設置
上傳實例(VODUploadClient
)支持設置文件大小來控制是否需要啟用分片上傳。如果文件超過partSize設置的大小就會采用分片上傳。
/**
分片大小,默認值1024 * 1024。單位字節。如果文件超過partSize設置的大小就會采用分片上傳。
*/
void setPartSize(long partSize);
設置轉碼
上傳實例(VODUploadClient
)支持通過指定轉碼模板組ID設置轉碼。
/**
* 設置轉碼模板組Id。登錄點播控制臺,選擇配置管理 > 媒體處理配置 > 轉碼模板組,查看轉碼模板組ID。
*/
void setTemplateGroupId(String templateGroupId);
客戶端上傳SDK不支持通過工作流方式設置轉碼。
設置點播服務地域
上傳實例(VODUploadClient
)支持設置存儲地域。
/**
vod region,默認值"cn-shanghai"。
*/
void setRegion(String var);