使用JavaScript SDK上傳檔案 - ApsaraVideo VOD

本文介紹如何使用JavaScript SDK將媒體檔案（本地檔案或網路檔案）從用戶端上傳至點播儲存，提供相關SDK的整合及檔案上傳指引。

前提條件

您已經完成上傳相關的系統配置，包括啟用目標儲存地區的儲存地址和配置回調。操作指引請參見管理儲存Bucket及回調設定。
您已準備好用於調用點播服務的帳號。為避免阿里雲帳號AccessKey泄露帶來的安全風險，推薦您建立RAM使用者並授予其VOD相關許可權。然後使用RAM使用者的AK對（AccessKey ID和AccessKey Secret）訪問點播服務。操作指引請參見建立RAM使用者並授權。
JavaScript上傳SDK目前相容的瀏覽器是：
- IE 10及以上版本
- Edge
- 主流版本的Chrome/Firefox/Safari
- 主流版本的Android/iOS/WindowsPhone系統預設瀏覽器
下載SDK代碼：V1.5.6 JavaScript上傳SDK和Demo源碼（jquery和Vue）

上傳流程

用戶端上傳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服務返回上傳結果。
說明
上傳結果也可以通過提前配置回調接收上傳相關事件來監聽。

上傳憑證

說明

此處以音視頻上傳憑證為例進行說明，圖片上傳憑證需調用CreateUploadImage - 擷取圖片上傳地址和憑證介面擷取。

設定上傳地址和上傳憑證

設定上傳地址和上傳憑證方法在onUploadstarted回調裡調用，此回調的參數包含uploadInfo的值。

const {VideoId,UploadAuth,UploadAddress} = data;
uploader.setUploadAuthAndAddress(uploadInfo,UploadAuth,UploadAddress,VideoId);

參數名稱	參數描述
uploadInfo	將onUploadstarted回調中的第一個參數進行透傳
uploadAuth	CreateUploadVideo介面返回
uploadAddress	CreateUploadVideo介面返回
videoId	CreateUploadVideo介面返回

上傳憑證失效後恢複上傳
一般在onUploadTokenExpired回調中調用，用於上傳憑證到期後更新上傳憑證。uploadAuth為RefreshUploadVideo介面中返回的上傳憑證。
```
const {VideoId,UploadAuth,UploadAddress} = data;
uploader.resumeUploadWithAuth(UploadAuth);
```

設定STS Token

用於通過STS方式進行上傳時，設定上傳地址和上傳憑證方法。一般在onUploadstarted回調裡調用，此回調的參數包含uploadInfo的值。

var info = data.SecurityTokenInfo
uploader.setSTSToken(uploadInfo,info.AccessKeyId,info.AccessKeySecret,info.SecretToken);

參數名稱	參數描述
uploadInfo	將onUploadstarted回調中的第一個參數進行透傳
accessKeyId	CreateSecurityToken介面返回
accessKeySecret	CreateSecurityToken介面返回
secretToken	CreateSecurityToken介面返回

上傳STS Token失效後恢複上傳
一般在onUploadTokenExpired回調中調用，用於通過STS方式進行上傳時上傳憑證到期後更新上傳憑證。
```
var info = data.SecurityTokenInfo
uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
```

上傳檔案

使用JavaScript上傳SDK上傳檔案的基本操作步驟如下：

說明

如果Web端上傳中斷，重新上傳可能會產生404報錯。您可以將SDK版本升級至1.5.3及以上版本，再重新上傳即可。如需使用1.5.3之前版本重新上傳，請修改待上傳檔案名稱，不要與上傳中斷的檔案重名，避免報錯。
如需實現在一個頁面同時上傳多個檔案，可通過建立多個上傳執行個體來實現。一個上傳執行個體對應一個上傳檔案，一個上傳執行個體不能同時上傳多個檔案。

引入JavaScript上傳SDK。
JavaScript指令碼下載，請參見SDK下載。上傳SDK當前未提供完整的模組化載入支援，如果通過import或require引用檔案會導致報錯ReferenceError: OSS is not defined。可根據業務需要選擇使用如下兩種引用方式：
- （推薦）在HTML中通過script引用
```

  <script src="../lib/es6-promise.min.js"></script>
  <script src="../lib/aliyun-oss-sdk-6.17.1.min.js"></script>
  <script src="../aliyun-upload-sdk-1.5.5.min.js"></script>
```
- 模組化引用
  手動將OSS模組的內容賦值給Window，範例程式碼如下：
  說明
  如果已經在HTML通過script引用，則不需要重複引用。
```
import OSS from '../lib/aliyun-upload-sdk/lib/aliyun-oss-sdk-6.17.1.min'
window.OSS = OSS;
import '../lib/aliyun-upload-sdk/aliyun-upload-sdk-1.5.5.min'
```
請求上傳地址和憑證或請求STS臨時Token，用於上傳授權。
JavaScript上傳SDK中，檔案上傳流程包含從AppServer擷取上傳憑證（需要服務端接入）和檔案上傳到OSS Server（阿里雲能力）兩部分。接入JavaScript上傳時只需要關心從AppServer擷取上傳憑證並設定給上傳SDK即可，上傳憑證支援以下兩種擷取方式：
- 部署授權服務擷取上傳地址和憑證的操作指引請參見擷取上傳地址和憑證。
- 部署STS服務擷取STS臨時Token的操作指引請參見擷取STS臨時Token。
執行結果
使用擷取到的上傳地址和憑證或STS臨時Token作為入參初始化上傳執行個體。

使用上傳憑證（推薦）或STS臨時Token初始化上傳執行個體。

初始化上傳執行個體分為聲明初始化回調和初始化上傳執行個體兩步。

聲明初始化回調。

聲明AliyunUpload.Vod初始化回調。以下範例程式碼為初始化執行個體時，可傳入的配置：

說明

ApsaraVideo for VOD支援的服務地區及對應地區標識請參見點播地區標識。

展開查看代碼

var uploader = new AliyunUpload.Vod({
     // userID，用於標識上傳者的身份，必填，有值即可，可以是阿里雲帳號ID或者您自訂的使用者ID，您可以訪問阿里雲帳號中心（https://account.console.aliyun.com/）查看帳號ID
     userId:"122",
     // 上傳到ApsaraVideo for VOD的地區，預設值為'cn-shanghai'，
     //eu-central-1，ap-southeast-1
     region:"",
     // 分區大小預設1 MB，不能小於100 KB（100*1024）
     partSize: 1048576,
     // 並行上傳分區個數，預設5
     parallel: 5,
     // 網路原因失敗時，重新上傳次數，預設為3
     retryCount: 3,
     // 網路原因失敗時，重新上傳間隔時間，預設為2秒
     retryDuration: 2,
     // 開始上傳
     'onUploadstarted': function (uploadInfo) {
      },
     // 檔案上傳成功
     'onUploadSucceed': function (uploadInfo) {
      },
     // 檔案上傳失敗
     'onUploadFailed': function (uploadInfo, code, message) {
      },
     // 檔案上傳進度，單位：位元組
     'onUploadProgress': function (uploadInfo, totalSize, loadedPercent) {
      },
     // 上傳憑證或STS token逾時
     'onUploadTokenExpired': function (uploadInfo) {
      },
     // 全部檔案上傳結束
     'onUploadEnd':function(uploadInfo){
       }
  });

初始化上傳執行個體。請根據業務需求選擇用上傳地址和憑證方式或STS方式初始化上傳執行個體。

在onUploadstarted回調中，擷取或重新整理上傳憑證。根據實際情況，選擇初始化上傳執行個體的方法。

上傳地址和憑證方式（推薦）

以上傳音視頻為例，在上傳開始後觸發的onUploadstarted回調中調用setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress,videoId)方法進行設定，上傳圖片的邏輯與之類似。

上傳音視頻樣本

說明

當擷取到的上傳憑證（UploadAuth）到期時，會觸發onUploadTokenExpired回調，需要調用resumeUploadWithAuth(uploadAuth)方法，設定新的上傳憑證繼續上傳。

展開查看代碼

//開始上傳
//uploadInfo 包含要上傳的檔案資訊
// {
//   videoId: '', // videoId，由服務端返回的音/視頻ID
//   Endpoint: '', // OSS對外服務的訪問網域名稱
//   Bucket: '', // OSS儲存空間
//   Object: '' // OSS儲存資料的基本單元
// }
'onUploadstarted': function (uploadInfo) {
  // 上傳方式，需要根據uploadInfo.videoId是否有值（該值由SDK通過localstorage擷取），調用ApsaraVideo for VOD的不同介面擷取uploadauth和uploadAddress
  // 如果videoId有值，調用重新整理音視頻上傳憑證介面，否則調用擷取音視頻上傳地址和憑證介面
  // 上傳過程中，如果在點播控制台刪除了音頻或視頻，即videoId不存在了，則會產生衝突，會出現控制台不存在videoId，而瀏覽器存在videoId的情況，報InvalidVideo.NotFound錯誤。此時，需手動清除localstorage
  var url = '';
  if (uploadInfo.videoId) {
    //如果uploadInfo.videoId存在，調用重新整理音視頻上傳憑證介面
    url = 'refreshUrl'; // 此處URL需要替換為服務端AppServer對應的地址
  }
  else{
    //如果uploadInfo.videoId不存在，調用擷取音視頻上傳地址和憑證介面
    url = 'createUrl'; // 此處URL需要替換為您自己服務端的“擷取音視頻上傳地址和憑證”介面的對應服務地址，例如：https://xxxx.com/createUploadVideo
  }

  // 以下請求實現為樣本，用於示範設定憑證
  // 擷取UploadAuth, UploadAddress, VideoId可能因您自有服務端的實現有差異
  fetch(url)
    .then((res) => res.json())
    .then((data) => {
        uploader.setUploadAuthAndAddress(uploadInfo, data.uploadAuth, data.uploadAddress, data.videoId);
  });
},

//上傳憑證逾時
'onUploadTokenExpired': function (uploadInfo) {
  //實現時，根據uploadInfo.videoId調用重新整理音視頻上傳憑證介面重新擷取UploadAuth
  //從點播服務重新整理的uploadAuth，設定到SDK裡

  var url = 'refreshUrl'; // 此處URL需要替換為您自己服務端的“擷取音視頻上傳地址和憑證”介面的對應服務地址，例如：https://xxxx.com/createUploadVideo
  // 以下請求實現為樣本，用於示範設定憑證
  // 擷取UploadAuth, UploadAddress, VideoId可能因您自有服務端的實現有差異
  fetch(url)
    .then((res) => res.json())
    .then((data) => {
    uploader.resumeUploadWithAuth(data.UploadAuth);
  });
},

上傳圖片樣本

說明

圖片憑證逾時目前不支援重新整理憑證操作，若憑證逾時請您重新擷取憑證進行上傳，此前的ImageId將失效，您可以選擇刪除此ImageId。

展開查看代碼

//開始上傳
//uploadInfo 包含要上傳的檔案資訊
// {
//   ImageId: '', // ImageId，由服務端返回的圖片媒資ImageId
//   Endpoint: '', // OSS對外服務的訪問網域名稱
//   Bucket: '', // OSS儲存空間
//   Object: '' // OSS儲存資料的基本單元
// }
'onUploadstarted': function (uploadInfo) {
  // 上傳方式，需要根據uploadInfo.ImageId是否有值（該值由SDK通過localstorage擷取），調用ApsaraVideo for VOD的不同介面擷取uploadauth和uploadAddress
  // 上傳過程中，如果在點播控制台刪除了圖片，即ImageId不存在了，則會產生衝突，會出現控制台不存在imageId，而瀏覽器存在imageId的情況，會出現NotFound錯誤。此時，需手動清除localstorage
  var url = 'createUrl';   // 此處URL需要替換為您自己服務端的“擷取圖片上傳地址和憑證”介面的對應服務地址，例如：https://xxxx.com/createUploadImage
  // 擷取UploadAuth, UploadAddress, ImageId可能因您自有服務端的實現有所差異
  fetch(url)
    .then((res) => res.json())
    .then((data) => {
        uploader.setUploadAuthAndAddress(uploadInfo, data.UploadAuth, data.UploadAddress, data.ImageId);
  });
}

STS方式

在上傳開始後觸發的onUploadstarted回調中調用setSTSToken(uploadInfo, accessKeyId, accessKeySecret, secretToken);方法進行設定。

說明

當STS臨時Token逾時，會觸發onUploadTokenExpired回調，需要調用resumeUploadWithSTSToken(accessKeyId, accessKeySecret, secretToken)方法，設定新的STS繼續上傳。

展開查看代碼

onUploadstarted: function (uploadInfo) {
  // 如果是STSToken上傳方式, 需要調用uploader.setUploadAuthAndAddress方法
  var stsUrl = 'stsUrl';
  // 以下請求實現為樣本，用於示範設定憑證
  // 擷取 accessKeyId, accessKeySecret,secretToken 可能因您自有服務端的實現有差異
  fetch(stsUrl)
    .then((res) => res.json())
    .then((data) => {
    var info = data.SecurityTokenInfo
    uploader.setSTSToken(uploadInfo, info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
  });
},

onUploadTokenExpired: function (uploadInfo) {
  // 如果是上傳方式二即根據STSToken實現時，從新擷取STS臨時帳號用於恢複上傳
  // 上傳檔案過大時可能在上傳過程中sts token就會失效, 所以需要在token到期的回調中調用resumeUploadWithSTSToken 方法

  var stsUrl = 'stsUrl';
  // 以下請求實現為樣本，用於示範設定憑證
  // 擷取 accessKeyId, accessKeySecret,secretToken 可能因您自有服務端的實現有差異
  fetch(stsUrl)
    .then((res) => res.json())
    .then((data) => {
    var info = data.SecurityTokenInfo
    uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
  });
},

根據上傳的檔案類型構造上傳參數。

選擇上傳檔案。

 <form action="">
   <input type="file" name="file" id="files" multiple/>
 </form>
 userData = '';
 document.getElementById("files")
  .addEventListener('change', function (event) {
    for(var i=0; i<event.target.files.length; i++) {
      //邏輯代碼
    }
  });

將選中的檔案添加到上傳列表中。

uploader.addFile(file,null,null,null,'{"Vod":{}}');

參數名稱	是否必填	類型	參數描述
file	是	File	需要上傳的音視頻檔案。
endpoint	否	String	想要上傳到的endpoint，傳入null則由服務端決定。
bucket	否	String	想要上傳到的bucket，傳入null則由服務端決定。
object	否	String	想要上傳到的object，傳入null則由服務端決定。
paramData	否	String	當您使用STS方式上傳時，可以通過`paramData`設定音視頻或圖片的標題、描述等資訊，以及設定對音視頻的轉碼、回調等。 `paramData`是一個JSON對象字串，第一級的`Vod`是必須的，通過在`Vod`下添加`paramData`設定屬性實現。支援設定的屬性，請參見CreateUploadVideo - 擷取音視頻上傳地址和憑證或CreateUploadImage - 擷取圖片上傳地址和憑證。

介面樣本如下：

說明

paramData只有在STS方式上傳時需要在SDK指定，如果是上傳地址和憑證方式，則在擷取上傳憑證的介面（CreateUploadVideo或CreateUploadImage）的參數裡指定，無需在SDK裡指定paramData參數。
如果同時傳遞了WorkflowId和TemplateGroupId，以WorkflowId為準。

設定名稱和分類

var paramData = '{"Vod":{"Title":"test","CateId":"234"}}';

設定名稱和轉碼

var paramData = '{"Vod":{"Title":"test","TemplateGroupId":"e6bb587b5365ac38a41462a4940****"}}';

設定名稱和工作流程

var paramData = '{"Vod":{"Title":"test","WorkflowId":"e2d027f16b5ee9cdf126266d32d****"}}';

開始上傳。
1. 調用startUpload()方法開始上傳。
```
uploader.startUpload();
```
2. 檔案開始上傳後，onUploadProgress回調開始同步上傳進度。
3. 檔案上傳成功後，onUploadSucceed回調會返回上傳結果。

執行結果

音視頻上傳成功後會返回videoId作為音視頻ID，拿到videoId後需要擷取播放地址進行播放。更多資訊，請參見通過播放憑證播放。
圖片上傳完成後不會返回imageUrl，可事先配置回調事件為圖片上傳完成的回調設定，待收到圖片上傳完成的事件通知後，在該事件通知中可以擷取到圖片的URL（FileURL）。開啟URL鑒權後URL會有到期時間。更多資訊，請參見配置URL鑒權。

進階功能

上傳控制

停止上傳

說明

stopUpload要確保檔案正在上傳，有檔案上傳進度時才能工作。

uploader.stopUpload();

隊列管理

對於上傳中或者上傳完成的檔案，可以通過對應的API進行管理。支援的API如下：

擷取上傳檔案清單
傳回值為通過addFile添加的檔案資訊列表。其中的file屬性為對應的File類型的檔案，可以通過遍曆擷取到需要操作的檔案的index。
```
var list = uploader.listFiles();
for (var i=0; i<list.length; i++) {
    log("file:" + list[i].file.name);
}
```

刪除上傳檔案

uploader.deleteFile(index);//需要刪除的檔案index，對應listFiles介面返回列表中元素的索引

取消單個檔案上傳
說明
- cancelFile成功後會在控制台列印oss is cancel as error。這是SDK為了避免已上傳的部分分區檔案佔用儲存空間（如果佔用就會產生儲存費用）做的處理。
- 取消檔案上傳後，如果後續還需要繼續上傳該檔案，則需要先使用uploader.resumeFile(index);恢複該檔案後，再進行上傳。
```
uploader.cancelFile(index);
```
恢複單個檔案上傳
```
uploader.resumeFile(index);
```
清理上傳檔案清單
```
uploader.cleanList();
```

斷點續傳

在音視頻上傳過程中，由於某種原因（例如：頁面被關閉、瀏覽器崩潰等）沒有上傳完成，下次選擇同一個檔案上傳時， SDK會從上次完成的位置繼續上傳，並在onUploadstarted回調中擷取上傳憑證。使用上傳地址和憑證方式上傳時，使用者可以根據回調返回的videoId的值，調用ApsaraVideo for VOD的介面擷取斷點資訊。樣本如下：

onUploadstarted: function (uploadInfo) {
if (上傳方式1) {
  if(!uploadInfo.videoId)//這個檔案沒有上傳異常
  {
    //實際環境中調用ApsaraVideo for VOD的擷取上傳憑證介面
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId);
  }
  else//如果videoId有值，根據videoId重新整理上傳憑證
  {
    //實際環境中調用ApsaraVideo for VOD的重新整理上傳憑證介面，擷取憑證
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress);
  }
}
else(上傳方式2)
{
   //實際環境中調用擷取STS介面，擷取STS的值
   uploader.setSTSToken(uploadInfo, accessKeyId, accessKeySecret,secretToken);
}
}

擷取斷點資訊：

 uploader.getCheckpoint(file);