使用JavaScript SDK上传文件

本文介绍如何使用JavaScript SDK将媒体文件从本地上传至点播存储。

浏览器要求

浏览器

是否支持

版本

IE

✔️

IE 10及以上

Microsoft Edge

✔️

全部支持

Chrome

✔️

主流的浏览器版本

Firefox

✔️

Safari

✔️

Android系统默认浏览器

✔️

iOS系统默认浏览器

✔️

WindowsPhone系统默认浏览器

✔️

功能说明

JavaScript SDK 仅支持上传音/视频、图片,不支持上传辅助媒资。

SDKDemo下载地址

集成方式

上传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) {},
});

设置凭证

请先了解客户端上传的整体上传流程,并根据上传的授权方式部署对应的授权服务:

  1. 选择使用上传地址和凭证方式, 请在授权服务中获取上传地址和凭证

  2. 选择使用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中的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的值,调用视频点播的接口获取断点信息。示例如下:

// 开始上传
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发生异常时,可借助错误码快速定位原因,详细内容请参见客户端错误码