本文介紹如何使用JavaScript SDK將媒體檔案從本地上傳至點播儲存。
瀏覽器要求
瀏覽器 | 是否支援 | 版本 |
IE | ✔️ | IE 10及以上 |
Microsoft Edge | ✔️ | 全部支援 |
Chrome | ✔️ | 主流的瀏覽器版本 |
Firefox | ✔️ | |
Safari | ✔️ | |
Android系統預設瀏覽器 | ✔️ | |
iOS系統預設瀏覽器 | ✔️ | |
WindowsPhone系統預設瀏覽器 | ✔️ |
功能說明
JavaScript SDK 僅支援上傳音/視頻、圖片,不支援上傳輔助媒資。
SDK及Demo下載地址
SDK版本:1.5.7
更新時間:2024-01-30
整合方式
上傳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) {},
});
設定憑證
請先瞭解用戶端上傳的整體上傳流程,並根據上傳的授權方式部署對應的授權服務:
選擇使用上傳地址和憑證方式, 請在授權服務中擷取上傳地址和憑證。
選擇使用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中的 |
accessKeySecret | STS Token中的 |
secretToken | STS Token中的 |
添加檔案
監聽<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方式上傳時,可以通過
|
開始上傳
uploader.startUpload();檔案開始上傳後,
onUploadProgress回調開始同步上傳進度。檔案上傳成功後,
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 = '檔案上傳失敗!'
},進階功能
上傳加速
當您需要上傳較大檔案(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發生異常時,可藉助錯誤碼快速定位原因,詳細內容請參見用戶端錯誤碼。