全部產品
Search
文件中心

ApsaraVideo VOD:使用JavaScript SDK上傳檔案

更新時間:Jul 15, 2025

本文介紹如何使用JavaScript SDK將媒體檔案從本地上傳至點播儲存。

瀏覽器要求

瀏覽器

是否支援

版本

IE

✔️

IE 10及以上

Microsoft Edge

✔️

全部支援

Chrome

✔️

主流的瀏覽器版本

Firefox

✔️

Safari

✔️

Android系統預設瀏覽器

✔️

iOS系統預設瀏覽器

✔️

WindowsPhone系統預設瀏覽器

✔️

功能說明

JavaScript SDK 僅支援上傳音/視頻、圖片,不支援上傳輔助媒資。

SDK及Demo下載地址

整合方式

上傳SDK依賴OSS SDK,請正確賦值window.OSS。否則可能會出現類似ReferenceError: OSS is not defined的報錯。

在HTML中通過<script>標籤匯入(推薦)

<!--  IE需要es6-promise,目前支援IE 10及以上 -->
  <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.7.min.js"></script>

模組化匯入

手動將OSS模組的內容賦值給window.OSS,範例程式碼如下:

說明

如果已經在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.7.min'

基礎設定

初始化上傳執行個體

  • 初始化SDK執行個體時必須傳入userId用於標識上傳者的身份,必填,有值即可,可以是阿里雲帳號ID或者您自訂的使用者ID,您可以訪問阿里雲帳號中心查看帳號ID。如果沒有傳userId或傳值為空白則會報錯。

  • region欄位需要結合ApsaraVideo for VOD支援的點播地區標識填寫。

var uploader = new AliyunUpload.Vod({
  // userID,用於標識上傳者的身份,必填,有值即可,可以是阿里雲帳號ID或者您自訂的使用者ID,您可以訪問阿里雲帳號中心(https://account-console.alibabacloud.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) {},
});

設定憑證

請先瞭解用戶端上傳的整體上傳流程,並根據上傳的授權方式部署對應的授權服務:

  1. 選擇使用上傳地址和憑證方式, 請在授權服務中擷取上傳地址和憑證

  2. 選擇使用STS Token方式,請在授權服務中擷取STS Token

返回的授權資訊統一在onUploadstarted回調裡設定,當憑證失效時會在onUploadTokenExpired回調中響應,需要調用重新整理憑證的方法重新擷取。

上傳地址和憑證方式

設定上傳地址和憑證需要調用setUploadAuthAndAddress,當憑證到期,會觸發onUploadTokenExpired回調,需要調用resumeUploadWithAuth方法,設定新的憑證繼續上傳。

// 開始上傳
onUploadstarted: function (uploadInfo) {
  let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
  axios.get(refreshUrl).then(({data}) => {
    let uploadAuth = data.UploadAuth
    let uploadAddress = data.UploadAddress
    let videoId = data.VideoId
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)
  })
},
// 上傳憑證逾時
onUploadTokenExpired: function (uploadInfo) {
  // 上傳大檔案逾時, 如果是上傳方式一即根據 UploadAuth 上傳時
  // 需要根據 uploadInfo.videoId 調用重新整理視頻上傳憑證介面重新擷取 UploadAuth
  // 然後調用 resumeUploadWithAuth 方法, 這裡是測試介面, 所以我直接擷取了 UploadAuth
  let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
  axios.get(refreshUrl).then(({data}) => {
    let uploadAuth = data.UploadAuth
    uploader.resumeUploadWithAuth(uploadAuth)
    console.log('upload expired and resume upload with uploadauth ' + uploadAuth)
  })
  self.statusText = '檔案逾時...'
},

方法說明:

uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress, videoId)
uploader.resumeUploadWithAuth(uploadAuth)

參數名稱

參數描述

uploadInfo

將onUploadstarted回調中的第一個參數進行透傳。

uploadAuth

CreateUploadVideo介面返回的上傳憑證。

uploadAddress

CreateUploadVideo介面返回的上傳地址。

videoId

CreateUploadVideo介面返回的音/視頻 ID.

STS Token方式

設定STS Token需要調用setSTSToken,當STS Token失效時,會觸發onUploadTokenExpired回調,需要調用resumeUploadWithSTSToken方法,設定新的STS Token繼續上傳。

 /*回調方法-開始上傳*/
 onUploadstarted: function (uploadInfo) {
    let stsUrl = "***.***.stsUrl" /*擷取STS Token 使用setSTSToken方法*/
    axios.get(stsUrl).then(({data}) => {
          var info = data.SecurityTokenInfo
          uploader.setSTSToken(uploadInfo, info.AccessKeyId, info.AccessKeySecret, info.SecretToken);
     })
 },
/*回調方法-憑證逾時*/
 onUploadTokenExpired: function (uploadInfo) { 
     let stsUrl = "***.***.stsUrl"  /*重新整理STS Token 使用resumeUploadWithSTSToken方法*/
     axios.get(stsUrl).then(({data}) => {
         var info = data.SecurityTokenInfo  
         uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);      
     })
 },

方法說明:

uploader.setSTSToken(uploadInfo, accessKeyId, accessKeySecret, secretToken)
uploader.resumeUploadWithSTSToken(accessKeyId, accessKeySecret, secretToken)

參數名稱

參數描述

uploadInfo

將onUploadstarted回調中的第一個參數進行透傳。

accessKeyId

STS Token中的AccessKeyId欄位。

accessKeySecret

STS Token中的AccessKeySecret欄位。

secretToken

STS Token中的SecretToken欄位。

添加檔案

監聽<input type="file" /> 表單項的change事件,將檔案添加到uploader的上傳列表中。

JavaScript 原生

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

Vue

 <template>
  <input type="file" id="fileUpload" @change="fileChange($event)">
 </template>

<script>
  export default {
    data () {
      return {
        file: null,
      }
    },
    methods: {
      fileChange (e) {
        this.file = e.target.files[0]
        if (!this.file) {
          alert("請先選擇需要上傳的檔案!")
          return
        }
        var Title = this.file.name
        var userData = '{"Vod":{}}'
        if (this.uploader) {
          this.uploader.stopUpload()
        }
        // 請先初始化一個 uploader
        this.uploader = this.createUploader() 
        this.uploader.addFile(this.file, null, null, null, userData)
      },
    }
  }
</script>

方法說明:

uploader.addFile(file,endpoint,bucket,object,paramData)

參數名稱

是否必填

類型

參數描述

file

File

需要上傳的音視頻檔案。

endpoint

String

想要上傳到的endpoint,傳入null則由服務端決定。

bucket

String

想要上傳到的bucket,傳入null則由服務端決定。

object

String

想要上傳到的object,傳入null則由服務端決定。

paramData

String

當您使用STS方式上傳時,可以通過paramData設定音視頻或圖片的標題、描述等資訊,以及設定對音視頻的轉碼、回調等。

paramData是一個JSON對象字串,如 '{"Vod":{}}'。第一級的Vod是必須的,通過在Vod下添加屬性實現。支援設定的屬性為CreateUploadVideo - 擷取音視頻上傳地址和憑證CreateUploadImage - 擷取圖片上傳地址和憑證介面的入參。

開始上傳

uploader.startUpload();
  1. 檔案開始上傳後,onUploadProgress回調開始同步上傳進度。

  2. 檔案上傳成功後,onUploadSucceed回調會返回上傳結果。

顯示進度

// 檔案上傳進度,單位:位元組, 可以在這個函數中拿到上傳進度並顯示在頁面上
onUploadProgress: function (uploadInfo, totalSize, progress) {
  console.log("onUploadProgress:file:" + uploadInfo.file.name + ", fileSize:" + totalSize + ", percent:" + Math.ceil(progress * 100) + "%")
  let progressPercent = Math.ceil(progress * 100)
  self.authProgress = progressPercent
  self.statusText = '檔案上傳中...'
},

上傳結果

// 檔案上傳成功
onUploadSucceed: function (uploadInfo) {
  console.log("onUploadSucceed: " + uploadInfo.file.name + ", endpoint:" + uploadInfo.endpoint + ", bucket:" + uploadInfo.bucket + ", object:" + uploadInfo.object)
  self.statusText = '檔案上傳成功!'
},
// 檔案上傳失敗
onUploadFailed: function (uploadInfo, code, message) {
  console.log("onUploadFailed: file:" + uploadInfo.file.name + ",code:" + code + ", message:" + message)
  self.statusText = '檔案上傳失敗!'
},
  • 確認視頻上傳成功後,您可通過videoId擷取播放地址進行播放。更多資訊,請參見擷取播放憑證

  • 圖片上傳完成後不會返回imageUrl,可通過回調設定,擷取到圖片的URL。

進階功能

上傳加速

當您需要上傳較大檔案(GB、TB層級)或進行跨地區上傳(比如在中國內地將視頻上傳到新加坡儲存地區的儲存地址)時,您可以啟用上傳加速功能。

開通上傳加速功能需提交工單,您需要提供阿里雲帳號UID和需要使用上傳加速的儲存地址

上傳地址和憑證方式

如果您採用上傳地址和憑證方式上傳,請在CreateUploadVideo - 擷取音視頻上傳地址和憑證介面的自訂參數UserData中增加相應的key-value值,以設定加速配置。樣本如下:

UserData={
  "AccelerateConfig": {
    "Type": "oss",
    "Domain": "https://oss-accelerate.aliyuncs.com"
  }
}

STS Token方式

如果您採用STS Token方式進行檔案上傳,您需要在調用addFile方法時,在參數paramData中增加UserData屬性,並配置上傳內容。樣本如下:

uploader.addFile(file,null,null,null,'{"Vod":{"UserData":{"AccelerateConfig":{"Type":"oss","Domain":"https://oss-accelerate.aliyuncs.com"}}}}');

UserData參數說明

名稱

類型

必填

描述

userData

string

自訂設定。為 JSON 字串,支援訊息回調、上傳加速等設定。更多資訊,請參見 。

加速配置參數說明:

名稱

類型

說明

Type

string

開啟上傳加速的類型(僅支援oss)。

Domain

string

使用者bucket的加速地址(預設為https)。

說明

使用開通後分配的一個加速地址,例如:vod-*******.oss-accelerate.aliyuncs.com。

更多關於UserData設定請參考請求參數說明

停止上傳

說明

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

uploader.stopUpload();

隊列管理

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

  • 擷取上傳檔案清單

    傳回值為通過addFile添加的檔案資訊列表。其中的file屬性為對應的File類型的檔案,可以通過遍曆擷取到需要操作的檔案的index。

    var list = uploader.listFiles();
    for (var i=0; i<list.length; i++) {
        console.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) {
  // 如果是 UploadAuth 上傳方式, 需要調用 uploader.setUploadAuthAndAddress 方法
  // 如果是 UploadAuth 上傳方式, 需要根據 uploadInfo.videoId是否有值,調用點播的不同介面擷取uploadauth和uploadAddress
  // 如果 uploadInfo.videoId 有值,調用重新整理視頻上傳憑證介面,否則調用建立視頻上傳憑證介面
  // 注意: 這裡是測試 demo 所以直接調用了擷取 UploadAuth 的測試介面, 使用者在使用時需要判斷 uploadInfo.videoId 存在與否從而調用 openApi
  // 如果 uploadInfo.videoId 存在, 調用 重新整理視頻上傳憑證介面
  // 如果 uploadInfo.videoId 不存在,調用 擷取視頻上傳地址和憑證介面
  if (!uploadInfo.videoId) {
    let createUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/CreateUploadVideo?Title=testvod1&FileName=aa.mp4&BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&VideoId=5bfcc7864fc14b96972842172207c9e6'
    axios.get(createUrl).then(({data}) => {
      let uploadAuth = data.UploadAuth
      let uploadAddress = data.UploadAddress
      let videoId = data.VideoId
      uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)                
    })
    self.statusText = '檔案開始上傳...'
    console.log("onUploadStarted:" + uploadInfo.file.name + ", endpoint:" + uploadInfo.endpoint + ", bucket:" + uploadInfo.bucket + ", object:" + uploadInfo.object)
  } else {
    // 列印斷點資訊
    console.log(uploader.getCheckpoint(uploadInfo.file));
    // 如果videoId有值,表示之前的視頻沒有上傳成功,則會從斷點處繼續上傳,根據videoId重新整理上傳憑證
    let refreshUrl = 'https://demo-vod.cn-shanghai.aliyuncs.com/voddemo/RefreshUploadVideo?BusinessType=vodai&TerminalType=pc&DeviceModel=iPhone9,2&UUID=59ECA-4193-4695-94DD-7E1247288&AppVersion=1.0.0&Title=haha1&FileName=xxx.mp4&VideoId=' + uploadInfo.videoId
    axios.get(refreshUrl).then(({data}) => {
      let uploadAuth = data.UploadAuth
      let uploadAddress = data.UploadAddress
      let videoId = data.VideoId
      uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)
    })
  }
}

擷取斷點資訊:

 uploader.getCheckpoint(file);

異常處理

使用JavaScript SDK發生異常時,可藉助錯誤碼快速定位原因,詳細內容請參見用戶端錯誤碼