使用Android SDK上傳檔案 - ApsaraVideo VOD

檔案上傳是指將媒體檔案（本地檔案或網路檔案）從用戶端上傳至點播儲存。在Android端上，檔案上傳通過上傳執行個體（VODUploadClient）完成。視頻上傳成功後會返回videoId作為視頻ID，使用者需要通過拿到videoId自行擷取播放地址進行播放。本文介紹如何使用Android端上傳SDK完成媒體檔案上傳。

前提條件

您已整合Android端上傳SDK。詳情請參見整合Android端上傳SDK。

上傳流程

用戶端上傳SDK封裝了OSS上傳邏輯。在用戶端上傳媒體檔案時，會直接將檔案上傳到點播儲存（基於OSS），不會再經服務端進行中轉，故用戶端上傳必須進行鑒權，也就是需要您在應用伺服器上部署授權服務以擷取上傳地址和憑證。目前用戶端上傳SDK支援兩種授權方式：

使用上傳地址和憑證授權：建議整合點播服務端SDK來擷取上傳地址和憑證。
使用STS方式授權：需要提前為RAM使用者建立角色並授權，也需要自行搭建STS授權服務。

上傳地址和憑證方式上傳流程詳解

以整合點播服務端SDK擷取上傳地址和憑證為例，完整的上傳流程如下圖所示：用戶端SDK上傳憑證上傳流程

使用者在上傳應用伺服器部署授權服務（如整合點播服務端SDK）用於擷取上傳地址和憑證。
用戶端向上傳應用伺服器發起請求擷取上傳地址和憑證。
上傳應用伺服器向ApsaraVideo for VOD服務發起請求擷取上傳地址和憑證。
點播服務返回上傳地址和憑證。
說明
點播服務在下發上傳地址和憑證時還會自動建立媒資資訊，即媒體ID（MediaId），用於媒資生命週期管理或ApsaraVideo for Media Processing。
- 擷取視頻上傳地址和憑證返回的VideoId即媒體ID。
- 擷取圖片上傳地址和憑證返回的ImageId即媒體ID。
- 擷取輔助媒資上傳地址和憑證返回的MediaId即媒體ID。
- 請妥善儲存媒體ID，作為媒資管理、音視頻播放、ApsaraVideo for Media Processing等的輸入。
上傳應用伺服器向用戶端下發上傳地址和憑證。
重要
下發地址和憑證即可，無需Base64解碼。
用戶端使用上傳地址和憑證初始化上傳執行個體。
用戶端構造上傳參數發起上傳請求。
OSS服務返回上傳結果。
說明
上傳結果也可以通過提前配置回調接收上傳相關事件來監聽。

STS方式上傳流程詳解

使用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屬性。

執行結果

視頻上傳成功後會返回videoId作為視頻ID，拿到videoId之後需要擷取播放地址進行播放。更多資訊，請參見通過播放憑證播放。
圖片上傳完成後會返回imageUrl，開啟URL鑒權後imageUrl會有到期時間。更多資訊，請參見URL鑒權。

進階功能

隊列管理

上傳執行個體（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）支援指定上傳檔案的儲存地址。不指定時檔案上傳到預設儲存地址。儲存地址需要提前啟用或配置。更多資訊請參見儲存說明。

/**
* 指定檔案的儲存地址。登入點播控制台，選擇組態管理 > 媒資管理配置 > 儲存管理查看儲存地址。
*/
void setStorageLocation(String storageLocation);

設定轉碼

上傳執行個體（VODUploadClient）支援通過指定轉碼模板組ID設定轉碼。

/**
* 設定轉碼模板組Id。登入點播控制台，選擇組態管理 > ApsaraVideo for Media Processing配置 > 轉碼模板組，查看轉碼模板組ID。
*/
void setTemplateGroupId(String templateGroupId);

重要

用戶端上傳SDK不支援通過工作流程方式設定轉碼。

斷點續傳

用戶端上傳SDK支援斷點續傳。使用者僅需保證以下方法的值為YES。

/**
 * 是否記錄上傳進度（斷點續傳），預設值YES。僅當參數值設為YES時上傳SDK內部自動實現斷點續傳。如果設定為NO，斷點續傳功能為關閉狀態。
 */
void setRecordUploadProgressEnabled(boolean var1);

設定點播服務地區

上傳執行個體（VODUploadClient）支援設定儲存地區。

/**
 vod region，預設值"cn-shanghai"。
 */
void setRegion(String var);