You need to enable JavaScript to run this app.
导航
接口说明
最近更新时间:2024.06.13 21:17:19首次发布时间:2021.02.23 10:42:41

Web 上传 SDK 支持视频、图片、普通文件的上传。本文介绍 Web 上传 SDK 的相关参数、方法、生命周期和错误码等内容。

配置

initConfig

在初始化 TTUploader 实例时,您可以通过 initConfig 进行初始化配置。

const uploader = new TTUploader(initConfig);

initConfig 支持的参数如下表所示。

参数
类型是否必传
默认值
描述
userIdStringnull用户 ID。用于进行单点追踪日志,定位某一个用户的日志,请设置一个唯一 ID。
appIdNumbernull应用 ID。用于定位某一条业务线的日志。
regionStringcn-north-1上传地区。当前仅支持设为 cn-north-1,即华北。
videoConfigvideoConfignull上传视频或普通文件使用到的配置。

useFileExtension

Boolean

false

是否带上文件扩展名。

说明

类型为 Object 时,上传设置有效。

useLocalStorageBooleantrue是否开启本地缓存写入上传信息。默认开启;关闭则断点续传失效。

useServerCurrentTime

Boolean

false

是否使用 STSToken 中的 CurrentTime 作为请求时间。该参数取值为 true 时,可以避免因为用户本地时间不准确导致的请求过期问题。

说明

CurrentTime 需为能被 Date.parse() 正常解析的日期格式字符串,即 RFC2822 或 ISO 8601。

taskParallelLimit

Number

3

单个 Uploader 实例下,设置并行上传的文件数量。

说明

  • 适用于多次调用 addFile 方法添加多个文件同时上传的场景。
  • 添加文件的数量大于该值时会串行排队执行上传。

videoConfig

videoConfig 为视频或普通文件上传专用配置,支持的参数如下表所示。

参数
类型是否必传默认值
描述
spaceNameStringnull空间名,在视频点播控制台中创建。

示例代码如下:

videoConfig: {
    spaceName: 'xxx', 
}
方法

本节为您介绍 Web 上传 SDK 提供的方法。

addFile(fileOption)

添加视频文件。调用该方法时,您需传入 fileOption。该方法返回当前文件的 key 值,在启动和取消文件上传时使用。示例代码如下:

const key = uploader.addFile({
    file: Blob, // 上传文件的 Blob 对象
    stsToken: {},
    type: 'video',
    processAction: [
        {
            Name: 'GetMeta'
        },
        {
            Name: 'StartWorkflow',
            Input: {
                TemplateId: '25524a2dae4541db93b2e891d******' // 工作流模板 ID
            }
        },
        {
            Name: 'Snapshot',
            Input: {
                SnapshotTime: 2
            }
        }
    ]
});
console.log(key);  // 示例:file_1495442273603_999031

fileOption

fileOption 支持的参数如下表所示。

参数
类型是否必传默认值
描述
fileBlobnull上传的文件。
stsTokenObjectnull上传签名。

type

String

video

上传文件类型。取值如下:

  • video
  • image
  • object
  • media
callbackArgsStringnull回调时回传给用户,用于客户端上传时,您希望透传客户端的一些信息。

fileName

String

null

文件路径,文件在点播存储中的存储位置,等同于传统对象存储的对象键(ObjectKey)概念。最大不超过 1024 个字符。您可根据业务需求自定义文件路径。

说明

  • 视频点播的文件路径必须携带文件后缀,例如,".mp4"。不强制要求携带文件前缀。
  • 具体的字符规则,请见文件命名通用字符规则
  • 设置 FileName 后, 当 FileName 相同时,有文件覆盖的风险。您需确保不同文件的 FileName 不同。
  • 传入 FileName 后,不需要再传入 FileExtension 参数。

fileExtension

String

null

文件后缀,点播存储中文件的类型。

说明

  • 当您传入 fileExtension 时,不需要重复传入 fileName 参数,视频点播将生成 32 位随机字符串,和您传入的 fileExtension 共同拼接成文件路径。
  • . 开头,不超过 8 位。

storageClass

Number

1

存储类型。取值如下:

  • 1: 标准存储。
  • 2: 归档存储。
processActionArray of processActionnull视频/文件上传后的处理 Action 对象数组。有多个处理请求时可以配置多个动作对象。对象中的 input 会被透传到对应的处理服务中。

processAction

processAction 对象的结构如下表所示。

参数类型是否必传默认值描述
NameStringAction 名称
InputObjectAction 输入

processAction 对象目前支持的 Action 如下表所示。

Action 名称Action 输入描述返回上传结果
GetMetavoid获取 Meta 信息。若不传,上传成功与否不依赖抽取 Meta,可能取到 Meta 也可能没有 Meta;若传,则获取 Meta 与上传成功强绑定,当获取 Meta 失败的时候,上传失败。VideoMeta/ObjectMeta

StartWorkflow

StartWorkflowInput

触发工作流配置。

注意

上传和触发工作流为异步过程,工作流触发失败不影响上传任务提交成功,使用此方法请注意关注工作流执行情况。

void

SnapshotSnapshotInput截图配置。默认抽第一帧,可以指定视频时间点抽帧做封面图。PosterUri
AddOptionInfoAddOptionInfoInput添加可选信息。void
StartWorkflowInput

StartWorkflowInput 支持的参数如下表所示。

参数类型是否必传默认值描述
TemplateIdString工作流模板 ID,从视频点播控制台配置并获取。
SnapshotInput

SnapshotInput 支持的参数如下表所示。

参数类型是否必传默认值描述
SnapshotTimeFloat截图时间
AddOptionInfoInput

AddOptionInfoInput 支持的参数如下表所示。

参数
类型是否必传默认值描述
TitleString标题
TagsString多个标签可用逗号隔开
DescriptionString描述信息

RecordType

Int

1

  • 1: 普通音视频。
  • 2: 素材。

说明

音视频和素材的定义详见媒资上传概述

Category

String

分类信息。当上传类型为素材时,可以指定素材的分类信息,必填。可选值如下所示。

  • video:视频
  • audio:音频
  • image:图片
  • dynamic_img:动图
  • subtitle:字幕
  • font:字体
FormatString格式。若传入 Format 的话,以您传入参数为准,否则以系统识别出的 Format 为准。若遇到特殊文件无法识别,Format 可能为空。
ClassificationIdint64分类 ID,可在控制台系统设置 > 分类管理中查看或通过媒资分类 OpenAPI 查询,素材不支持分类。

fileOption.typeAddOptionInfoInput.Category 参数取值的对应关系如下表所示。

type 取值类型对应 Category 取值
mediaStringvideo、audio
imageStringimage、dynamic_img
objectStringsubtitle、font

start(key)

启动上传任务。如果上传被暂停,则再次调用此方法时将从断点处开始上传。调用该方法时,您需传入文件的 key 值;如不传,则开始所有文件的上传。示例代码如下:

uploader.start();

removeFile(key)

移除某个待上传的文件或者取消该文件的上传。其中,key 值从 addFile 方法中返回。示例代码如下:

uploader.removeFile('file_1495442273603_999031');

cancel(key)

取消某一文件的上传,同时删除暂存的上传信息。调用该方法时,您需传入文件的 key 值;如不传,则取消所有文件的上传。示例代码如下:

uploader.cancel();

pause(key)

暂停上传,将暂存当前文件的上传信息。调用该方法时,您需传入文件的 key 值;如不传,则暂停所有文件的上传。示例代码如下:

uploader.pause();
生命周期

此处的生命周期是指上传某一个文件时候的生命周期,即一个视频上传产品线上的各个任务。

捕获某个生命周期的示例代码如下所示。

uploader.on('xxx', function(data) {
    console.log('xxx', data);
});

生命周期各阶段如下表所示。

过程名称描述备注
crc32文件分片并获取 crc32完成后得到 crc32Array(crc32 信息数组)和 sliceLength(每个分片的长度)
preUpload获取视频上传信息完成后得到 signature(上传签名)、token(complete 时依赖 token)、oid 和 vid
initUploadID初始化分片上传完成后得到上传所需的 uploadID
progress视频并行分片上传进行中实时更新 percent(总体进度)
fileMerge分片上传成功,合并文件
complete视频上传并获取封面完成部分已开获取分片权限的用户,上传完成后可得到 video 和 poster

Returned Value

在捕获每一个生命周期时都可获得描述当前状态的 data 信息,该信息在整个周期中不断完善,最终得到的 data 信息如下表所示:

参数
描述
uploadResult上传完成后的各种信息,包括 vid,uri 等(complete 获取)。详见 uploadResult
startTime文件开始上传的时间戳
endTime文件完成上传的时间戳
stageStartTime各阶段开始时间戳
stageEndTime各阶段完成时间戳
duration各阶段持续时间,计算公式:stageEndTime - stageStartTime
extra当前状态的描述(随着生命周期不断变化)
fileSize当前视频文件大小(crc32 获取)
key当前视频文件的 key(addFile 时自动生成)
oid存放的文件 ID (preUpload 获取)
percent当前上传总体进度百分比(%)
signature上传所需的签名信息(preUpload 获取)
sliceLength每一个分片的 size(crc32获取)
stage当前所处生命周期,如果是不支持的浏览器,则该值为'browserError'

status

文件上传运行状态。取值如下:

  • 1 代表正在运行;
  • 2 代表取消运行;
  • 3 代表暂停运行。
task队列实例
type当前任务状态,成功/失败
uploadID上传所需的 uploadID( initUploadID 获取)

uploadResult

视频上传

对于视频上传的返回结果,默认情况下只会返回 Vid,如果想获取详细的视频 meta 信息、封面图,请在上传时添加配置。

参数
类型描述
VidString视频 id,vid 是视频在视频架构中的唯一 id
PosterUriString封面图 uri,当添加有截取封面信息的配置时返回
VideoMetaObject视频meta信息,当添加有获取 meta 信息的配置时返回
VideoMeta.DurationNumber视频时长,单位:秒
VideoMeta.WidthNumber视频宽度
VideoMeta.HeightNumber视频高度
VideoMeta.FormatString视频格式
VideoMeta.BitrateNumber视频码率,单位:bps
VideoMeta.FileTypeString文件类型
VideoMeta.SizeNumber视频文件大小
VideoMeta.Md5String视频文件 md5 值
VideoMeta.UriString视频源文件在 tos 中的 uri,获取视频播放地址请不要使用这种方式访问
SourceInfo.VodVideoStreamMetaObject视频流 meta 信息,当添加有获取 meta 信息的配置时返回
VideoStreamMeta.DurationNumber视频时长,单位:秒
VideoStreamMeta.WidthNumber视频宽度
VideoStreamMeta.HeightNumber视频高度
VideoStreamMeta.CodecString视频编码格式
VideoStreamMeta.BitrateNumber视频流码率,单位:bps
VideoStreamMeta.DefinitionString视频清晰度
VideoStreamMeta.FpsNumber视频流帧率
AudioStreamMetaObject音频流 meta 信息
AudioStreamMeta.CodeString音频编码格式
AudioStreamMeta.DurationNumber音频时长
AudioStreamMeta.SampleRateNumber音频采样率
AudioStreamMeta.BitrateNumber音频码率,单位:bps
AudioStreamMeta.QualityString音频质量

普通文件上传

参数类型描述
UriString源文件在 tos 中的 uri,格式为 bucket/oid
ObjectMetaObject文件 meta 信息,当添加有获取meta信息的配置时返回
ObjectMeta.Md5String文件 md5 值
ObjectMeta.UriString与上层中的 Uri 一致
错误码

详见上传 SDK 错误码