本文介绍如何使用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.5.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.5.min'
基础设置
初始化上传实例
初始化SDK实例时必须传入userId用于标识上传者的身份,必填,有值即可,可以是阿里云账号ID或者您自定义的用户ID,您可以访问阿里云账号中心查看账号ID。如果没有传userId或传值为空则会报错。
region
字段需要结合视频点播支持的点播地域标识填写。
var uploader = new AliyunUpload.Vod({
// userID,用于标识上传者的身份,必填,有值即可,可以是阿里云账号ID或者您自定义的用户ID,您可以访问阿里云账号中心(https://account.console.aliyun.com/)查看账号ID
userId: "122",
// 上传到视频点播的地域,默认值为'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) {
// https://help.aliyun.com/document_detail/55408.html?spm=a2c4g.11186623.6.630.BoYYcY
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 调用刷新视频上传凭证接口(https://help.aliyun.com/document_detail/55408.html)重新获取 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.sertUploadAuthAndAddress(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的值,调用视频点播的接口获取断点信息。示例如下:
// 开始上传
onUploadstarted: function (uploadInfo) {
// 如果是 UploadAuth 上传方式, 需要调用 uploader.setUploadAuthAndAddress 方法
// 如果是 UploadAuth 上传方式, 需要根据 uploadInfo.videoId是否有值,调用点播的不同接口获取uploadauth和uploadAddress
// 如果 uploadInfo.videoId 有值,调用刷新视频上传凭证接口,否则调用创建视频上传凭证接口
// 注意: 这里是测试 demo 所以直接调用了获取 UploadAuth 的测试接口, 用户在使用时需要判断 uploadInfo.videoId 存在与否从而调用 openApi
// 如果 uploadInfo.videoId 存在, 调用 刷新视频上传凭证接口(https://help.aliyun.com/document_detail/55408.html)
// 如果 uploadInfo.videoId 不存在,调用 获取视频上传地址和凭证接口(https://help.aliyun.com/document_detail/55407.html)
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刷新上传凭证
// https://help.aliyun.com/document_detail/55408.html?spm=a2c4g.11186623.6.630.BoYYcY
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发生异常时,可借助错误码快速定位原因,详细内容请参见客户端错误码。