使用JavaScript SDK上传文件_视频点播(VOD)-阿里云帮助中心

本文介绍如何使用JavaScript SDK将媒体文件（本地文件或网络文件）从客户端上传至点播存储，提供相关SDK的集成及文件上传指引。

前提条件

您已经完成上传相关的系统配置，详情可参照客户端上传。
下载SDK代码：V1.5.6 JavaScript上传SDK和Demo源码（jquery和Vue）。

环境要求

浏览器	是否支持	版本

浏览器	是否支持	版本
IE	✔️	IE 10及以上
Microsoft Edge	✔️	全部支持
Chrome	✔️	主流的浏览器版本
Firefox	✔️
Safari	✔️
Android系统默认浏览器	✔️
iOS系统默认浏览器	✔️
WindowsPhone系统默认浏览器	✔️

集成方式

JavaScript上传SDK下载，请参见SDK简介与下载。上传SDK当前未提供完整的模块化加载支持，如果通过import或require引用文件会导致报错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，示例代码如下：

说明

如果已经在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'

上传凭证

说明

本示例将以音视频上传凭证为例进行说明。您需要通过接口CreateUploadVideo获取音视频上传地址和凭证；若需获取图片上传凭证，则需调用接口CreateUploadImage 以获取图片上传地址和凭证。

从客户端直接上传文件到点播存储（基于OSS）前，需要获取上传地址和上传凭证或STS Token。设置方法统一在onUploadstarted回调里调用，此回调的参数包含uploadInfo的值；当凭证失效时会在onUploadTokenExpired回调中响应，这时需要在里面调用刷新凭证的方法重新获取。

凭证方式

 /*回调方法-开始上传*/
 onUploadstarted: function (uploadInfo) {
    let refreshUrl = "***.***.createUpload" /*获取凭证的接口*/
    axios.get(refreshUrl).then(({data}) => {
          let uploadAuth = data.UploadAuth
          let uploadAddress = data.UploadAddres
          let videoId = data.VideoId
          uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId)
     })
 }
/*回调方法-凭证超时*/
 onUploadTokenExpired: function (uploadInfo) {
     let refreshurl = "***.***.refreshurl"
     axios.get(refreshUrl).then(({data}) => {
         let uploadAuth = data.UploadAuth
         uploader.resumeUploadWithAuth(uploadAuth)       
     })
 }

参数名称	参数描述

参数名称	参数描述
uploadInfo	将onUploadstarted回调中的第一个参数进行透传
uploadAuth	CreateUploadVideo接口返回
uploadAddress	CreateUploadVideo接口返回
videoId	CreateUploadVideo接口返回

STS Token方式

 /*回调方法-开始上传*/
 onUploadstarted: function (uploadInfo) {
    let stsUrl = "***.***.stsUrl" /*获取STS Token 使用setSTSToken方法*/
    axios.get(refreshUrl).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(refreshUrl).then(({data}) => {
         var info = data.SecurityTokenInfo  
         uploader.resumeUploadWithSTSToken(info.AccessKeyId, info.AccessKeySecret, info.SecretToken);      
     })
 }

参数名称	参数描述

参数名称	参数描述
uploadInfo	将onUploadstarted回调中的第一个参数进行透传
accessKeyId	CreateSecurityToken接口返回
accessKeySecret	CreateSecurityToken接口返回
secretToken	CreateSecurityToken接口返回

上传流程

客户端上传SDK封装了OSS上传逻辑。在客户端上传媒体文件时，会直接将文件上传到点播存储（基于OSS），不会再经服务端进行中转，故客户端上传必须进行鉴权，也就是需要您在应用服务器上部署授权服务以获取上传地址和凭证。目前客户端上传SDK支持两种授权方式，两种方式的引入及对比如下：

差异性

凭证方式相比于STS Token方式授权较为简单、安全性较高（可以控制单个视频权限）、可灵活配置多种返回参数、冗余度较高等。两种方式的详细的区别请参见凭证方式与STS方式对比。

上传地址和凭证方式上传流程详解

STS方式上传流程详解

以集成点播服务端SDK获取上传地址和凭证为例，完整的上传流程如下图所示：客户端SDK上传凭证上传流程

用户在上传应用服务器上部署授权服务（如集成点播服务端SDK）用于获取上传地址和凭证。
客户端向上传应用服务器发起请求获取上传地址和凭证。
上传应用服务器向视频点播服务发起请求获取上传地址和凭证。
点播服务返回上传地址和凭证。
上传应用服务器向客户端下发上传地址和凭证。
说明
下发地址和凭证即可，无需Base64解码。
客户端使用上传地址和凭证初始化上传实例。
客户端构造上传参数发起上传请求。
OSS服务返回上传结果。
说明
- 点播服务在下发上传地址和凭证时还会自动创建媒资信息，即媒体ID（MediaId），用于媒资生命周期管理或媒体处理。
  - 获取音视频上传地址和凭证返回的VideoId即媒体ID。
  - 获取图片上传地址和凭证返回的ImageId即媒体ID。
  - 获取辅助媒资上传地址和凭证返回的MediaId即媒体ID。
  - 请妥善保存媒体ID，作为媒资管理、音视频播放、媒体处理等的输入。
- 上传结果也可以通过提前配置回调接收上传相关事件以监听。

使用STS临时授权方式（阿里云Security Token Service）访问点播服务，请为RAM用户创建角色并授予角色VOD相关权限。操作指引请参见使用STS临时授权方案上传视频。

使用STS方式上传的完整的流程如下图所示：客户端STS方式上传流程

用户在上传应用服务器上部署授权服务（如集成阿里云STS SDK）用于获取STS临时Token。
客户端向上传应用服务器发起请求获取STS临时Token。
上传应用服务器向阿里云STS服务发起请求获取STS临时Token。
阿里云STS服务返回上传地址和凭证。
上传应用服务器向客户端下发STS临时Token。
客户端使用STS临时Token初始化上传实例。
客户端构造请求发起上传请求。
OSS服务返回上传结果。
说明
上传结果也可以通过提前配置回调接收上传相关事件来监听。

上传文件

在使用JavaScript 上传文件的基本操作如下：

获取上传地址和凭证或STS临时Token，用于上传授权。
JavaScript上传SDK支持以下两种上传授权方式，推荐使用凭证方式：
- 部署授权服务获取上传地址和凭证的操作指引请参见获取上传地址和凭证。
- 部署STS服务获取STS临时Token的操作指引请参见获取STS临时Token。
说明
注意当前SDK只支持上传图片和音视频类型的文件详情请参见CreateUploadImage - 获取图片上传地址和凭证，CreateUploadVideo - 获取音视频上传地址和凭证。

设置回调，用于接收上传过程中关键节点的消息。

声明AliyunUpload.Vod初始化回调。以下示例代码为初始化实例时，可传入的配置：

说明

初始化SDK实例时必须传入userId用于标识上传者的身份，必填，有值即可，可以是阿里云账号ID或者您自定义的用户ID，您可以访问阿里云账号中心查看账号ID。如果没有传userId或传值为空则会报错。
视频点播支持的服务地域及对应地域标识请参见点播地域标识。

展开查看代码

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初始化上传实例。

在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获取），调用视频点播的不同接口获取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) => {
        let uploadAuth = data.UploadAuth
        let uploadAddress = data.UploadAddress
        let videoId = data.VideoId
        uploader.setUploadAuthAndAddress(uploadInfo,uploadAuth,uploadAddress,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获取），调用视频点播的不同接口获取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 Token方式

在上传开始后触发的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++) {
      //逻辑代码
    }
  });

将选中的文件添加到上传列表中。

/**
* 参数分别是 file，endpoint，bucket，object，paramData
*/
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为准。

paramData 部分内容如下：

参数名称	类型	描述

参数名称	类型	描述
Title	字符串	上传完成后，在点播中展示的音/视频标题。长度不超过 128 个字符。 UTF-8 编码。
CateId	字符串	分类 ID。可通过以下方式获取：登录点播控制台，选择配置管理>媒资管理配置>分类管理查看分类 ID。通过AddCategory - 创建分类接口创建分类时，分类 ID 为返回参数 CateId 的值。通过GetCategories - 获取分类及其子分类信息接口查询分类时，为请求后返回参数 CateId 的值。
TemplateGroupId	字符串	转码模板组 ID。可通过以下方式获取：登录点播控制台，选择配置管理>媒体处理配置>转码模板组查看转码模板组 ID。通过创建转码模板组接口创建转码模板组时，转码模板组 ID 为返回参数 TranscodeTemplateGroupId 的值。通过查询转码配置列表接口查询转码模板组时，为请求后返回参数 TranscodeTemplateGroupId 的值。
WorkflowId	字符串	工作流 ID。可登录点播控制台，选择配置管理>媒体处理配置>工作流管理查看工作流 ID。

开始上传。
1. 调用startUpload()方法开始上传。
  uploader.startUpload();
2. 文件开始上传后，onUploadProgress回调开始同步上传进度。
3. 文件上传成功后，onUploadSucceed回调会返回上传结果。

执行结果

音视频上传成功后会返回videoId作为音视频ID，拿到videoId后需要获取播放地址进行播放。更多信息，请参见通过播放凭证播放。
图片上传完成后不会返回imageUrl，可事先配置回调事件为图片上传完成的回调设置，待收到图片上传完成的事件通知后，在该事件通知中可以获取到图片的URL（FileURL）。开启URL鉴权后URL会有过期时间。更多信息，请参见配置URL鉴权。

高级功能

上传加速

当您需要上传较大文件（GB、TB级别）或进行跨区域上传（比如在中国内地将视频上传到新加坡存储地域的存储地址）时，您可以启用上传加速功能。详情请参见开通方式。

凭证方式

如果您采用凭证方式进行上传，您需要通过CreateUploadVideo - 获取音视频上传地址和凭证获取上传地址。在请求此接口时您应给自定义参数UserData中增加相应的key-value值，以设置加速配置。示例如下：

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

STS Token方式

如果您采用STS Token方式进行文件上传，您需要在调用addFile方法时，在参数parmData中增加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。

上传控制

停止上传

说明

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的值，调用视频点播的接口获取断点信息。示例如下：

onUploadstarted: function (uploadInfo) {
if (上传方式1) {
  if(!uploadInfo.videoId)//这个文件没有上传异常
  {
    //实际环境中调用视频点播的获取上传凭证接口
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress,videoId);
  }
  else//如果videoId有值，根据videoId刷新上传凭证
  {
    //实际环境中调用视频点播的刷新上传凭证接口，获取凭证
    uploader.setUploadAuthAndAddress(uploadInfo, uploadAuth, uploadAddress);
  }
}
else(上传方式2)
{
   //实际环境中调用获取STS接口，获取STS的值
   uploader.setSTSToken(uploadInfo, accessKeyId, accessKeySecret,secretToken);
}
}

获取断点信息：

 uploader.getCheckpoint(file);

异常处理

使用JavaScript SDK发生异常时，可借助错误码快速定位原因，详细内容请参见客户端错误码。