You need to enable JavaScript to run this app.
导航
集成小程序上传 SDK
最近更新时间:2023.10.27 17:27:11首次发布时间:2023.08.09 10:55:03

本文为您介绍如何集成小程序上传 SDK,支持微信小程序、抖音小程序。

适用版本

此文档适用于 TTSDK 2.0.0 及以上的版本,其他版本请参考历史版本小程序上传 SDK

接入准备

获取上传签名

上传前需要从服务端获取上传 stsToken 签名,签名算法服务端接入,具体请参考:服务端 SDK > 生成上传凭证 > 生成临时上传密钥

注意

由于签名计算放在前端会暴露 AccessKey 和 SecretKey,我们把签名计算过程放在后端实现。实现的方式如下:

  1. 利用签名 SDK 可以生成一对临时的 AK、SK。
  2. 前端向业务服务端获取签名结果。
  3. 正式部署时请在后端加一层自己网站本身的权限检验。

添加域名白名单

把网关地址和上传地址添加到小程序的访问白名单中。

  • request 合法域名:

    • https://vod.volcengineapi.com
    • https://mcs.zijieapi.com
    • https://tob-upload-x.volcvod.com
    • https://tob-upload-y.volcvod.com
    • https://tob-upload-x-d.volcvod.com
    • https://tob-upload-y-d.volcvod.com

    截图示例如下所示:

  • uploadFile 合法域名:

    • https://tob-upload-x.volcvod.com
    • https://tob-upload-y.volcvod.com
    • https://tob-upload-x-d.volcvod.com
    • https://tob-upload-y-d.volcvod.com

    截图示例如下所示:

Demo 示例

引入 npm 包

npm install tt-uploader-miniprogram

快速开始

import TTUploader from 'tt-uploader-miniprogram';

// 1. 初始化 uploader
const uploader = new TTUploader({
  userId: 'volcengine-user1',  //建议设置能识别用户的唯一标识 ID,用于上传出错时排查问题,不要传入非 ASCII 编码。
  appId: 8888,                 //在视频点播控制台应用管理中创建的 AppID,视频点播的质量监控等都是以这个参数来区分业务方的,务必正确填写。
  videoConfig: {
    spaceName: 'your spaceName' //在视频点播中创建的点播空间名。
  }
});

// 2. 设置监听事件
uploader.on('error', (info) => {
    console.log('上传失败', info)
})
uploader.on('progress', (infor) => {
    console.log('上传进度:', infor.percent)
});
uploader.on('complete', (info) => {
    console.log('上传成功', info)
})

// 3. 添加上传文件
const key = uploader.addFile({
   path: '',      // 文件临时路径,从 chooseMedia 回调中获取。
   size: 1234,    // 文件大小,从 chooseMedia 回调中获取。
   // 从服务端获取到的签名 token,见上方【获取上传签名说明】说明
   stsToken: {
       "CurrentTime":"2023-03-31T07:47:14.866Z",
       "ExpiredTime":"2023-05-30T07:47:14.866Z",
       "SessionToken":"STS2eyJU******MTlmZWEzNzBlNWQ4ZmU3NjAwMTljIn0=",
       "AccessKeyId":"AKTPZDM1ODg3MG******zODEyYmZiNTU5ODg",
       "SecretAccessKey":"aNXEA8uvCBF7tqtoolAxJ******l7KTZcaxyOWQbuPqg=="
   }, 
   type : 'media',       // 上传文件类型,三个可选值:(默认值)media(视频或者音频),image(图片),object(普通文件)
});

// 4. 开始上传
uploader.start(key)

详细配置及 API 说明

初始化配置

初始化 uploader 实例时,可配置的属性如下,示例如下:

const uploader = new TTUploader({
    userId: 'xxx',
    appId: 8888,
    
    //视频/普通文件上传必传字段
    videoConfig: {
        spaceName: 'your space name'
    },
    useFileExtension: true,
    uploadTimeout: 1000 * 60 * 30,
    gatewayTimeout: 1000 * 60 * 5
});

详细的参数说明如下表所示。

参数类型是否必传默认值描述
userIdStringnull用户 ID。用于进行单点追踪日志,定位某一个用户的日志,请设置一个唯一 ID。
appIdNumbernull应用 ID。用于定位某一条业务线的日志。
videoConfigObjectnull点播上传(视频/文件)专用配置。具体请参见下方videoConfig 详细参数说明

useFileExtension

Boolean

false

是否使用文件扩展名作为存储 URI 的后缀。

说明

小程序上传 SDK 根据文件路径自动截取文件后缀。

uploadTimeoutNumber30min上传文件请求的超时时间,单位为 ms。示例为 1000 * 60 * 30
gatewayTimeoutNumber5min网关请求的超时时间,单位为 ms。示例为 1000 * 60 * 5
videoConfig 详细参数说明如下表所示:
参数类型是否必传默认值描述
spaceNameStringnull空间名,在视频点播控制台中创建。

addFile(fileOption)

添加视频文件,传入的 fileOption 配置如下表所示。

参数类型是否必传默认值描述
pathStringnull上传的文件的临时路径。
sizeNumbernull上传文件的大小。
stsTokenObjectnull上传签名。

type

String

media

上传文件类型。可选值如下:

  • media

  • image

  • object

callbackArgsStringnull回调时回传给用户,用于客户端上传时,您希望透传客户端的一些信息。
fileNameStringnull文件路径。要求带上文件后缀。详细规则,具体请参见服务端ApplyUploadInfo 请求参数中的 FileName 的描述。
fileExtensionStringnull文件后缀名,用户传后缀时,文件名添加此后缀。 (以. 开头,不超过8位,与 FileName 互斥)

storageClass

Number

1

存储类型。取值如下:

  • 1:标准存储。

  • 2:归档存储。

processActionArray of processActionnull视频/文件上传后的处理 Action 对象,类型是一个数组,有多个处理请求时可以配置多个动作对象。对象中的 Input 会被透传到对应的处理服务中。

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

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

processAction

processAction 目前支持的 action 如下表所示。

action 名称action 输入描述返回上传结果

GetMeta

void

获取 Meta 信息。

  • 若不传,上传成功与否不依赖抽取 Meta,可能取到 Meta 也可能没有 Meta;

  • 若传,则获取 Meta 与上传成功强绑定,当获取 Meta 失败的时候,上传失败。

VideoMeta/ObjectMeta

StartWorkflow

StartWorkflowInput

触发工作流。

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

void

SnapshotSnapshotInput截图功能。默认抽第一帧,可以指定视频时间点抽帧做封面图。PosterUri,封面截图 Uri

AddOptionInfo

AddOptionInfoInput

添加媒资信息功能信息。

void

各个 action 的输入参数如下表所示。

StartWorkflowInput
参数类型是否必传默认值描述
TemplateIdString工作流模板 ID,从视频点播控制台配置并获取。
SnapshotInput
参数类型是否必传默认值描述
SnapshotTimeFloat截图时间
AddOptionInfoInput
参数类型是否必传默认值描述
TitleString标题
TagsString多个标签可用逗号隔开
DescriptionString描述信息

RecordType

Int

1

上传类型。取值如下:

  • 1:普通音视频。

  • 2 :素材。

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

Category

String

分类信息。

说明

RecordType 上传类型参数取值为2素材时,该Category参数支持指定素材的分类信息,同时是必选项。

可选值如下:

  • video:视频

  • audio:音频

  • image:图片

  • dynamic_img:动图

  • subtitle:字幕

  • font:字体

Format

String

格式。

说明

  • 若传入 Format 的话,以您传入参数为准,否则以系统识别出的 Format 为准。

  • 若遇到特殊文件无法识别,Format 可能为空。

ClassificationId

int64

分类 ID。获取方式如下:

  • 您可在控制台系统设置 > 分类管理中获取。

  • 通过媒资分类 OpenAPI 获取。

注意

素材不支持分类。

addFile 方法中 type 参数的取值和 Category 对应关系如下表所示。

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

该方法返回当前文件的 key 值时,在上传和取消上使用,代码示例如下所示:

const key = uploader.addFile({
    file: file, // 上传的文件对象
    stsToken: {},
    type: 'media',
    processAction: [
        {
            Name: 'GetMeta'
        },
        {
            Name: 'Snapshot',
            Input: {
                SnapshotTime: 2
            }
        }
    
    ]
});
console.log(key);  // file_1495442273603_999031 (类似格式)

start(key)

启动上传任务。如果该上传任务被暂停,则再次调用此方法时将恢复上传。传入文件的 key 值,如果不传参数,则所有已添加的文件将开始上传。

uploader.start();

pause(key)

暂停上传,将暂存当前文件的上传信息。传入文件的 key 值,如果不传参数,则将暂停所有文件的上传。

uploader.pause('file_1495442273603_999031');

restart(key)

恢复上传,将恢复当前被暂停的上传任务。传入文件的 key 值,如果不传参数,则将恢复所有文件的上传。

uploader.restart();

cancel(key)

取消某一文件的上传,同时删除暂存的上传信息。传入文件的 key 值,如果不传参数,则将取消所有文件的上传。

uploader.cancel();

回调事件说明

在文件上传的过程中,小程序上传 SDK 会依次抛出各类事件以通知外部,您可根据业务需要监听这些事件,事件名称和事件描述如下表所示:

事件名称事件描述
progress文件上传过程中会多次触发,可用于标识文件上传进度。详见 progress 事件
complete文件上传成功时触发,标识一个上传任务结束。详见 complete 事件
error上传失败、发生错误时触发。详见 error 事件
// 监听事件
uploader.on('progress', function(info) {
    console.log('上传进度:', info.percent);
});
uploader.on('complete', function(info) {
    console.log('上传成功:', info);
});
uploader.on('error', function(info) {
    console.error('上传失败:', info);
});

progress 事件

progress事件回调的参数如下所示:

属性类型描述

percent

Number

整体上传进度。单位为百分比。取值范围为 [0, 99],为整数。

说明

complete事件,触发后才认为进度为 100

totalSizeNumber上传文件的总体大小,单位为 byte。
sentSizeNumber此时已发送的字节数,单位为 byte。
keyString标识本次上传任务的字符串,由 addFile() 方法返回。
oidString文件存储的 URI(统一资源标识符)。
sliceIndexNumber可选,在分片上传的场景下,标识此索引的分片上传完成。
uploadIdString可选,在分片上传的场景下,标识此次上传的唯一 ID。

complete 事件

complete事件回调的参数如下所示:

属性类型描述
filePathString文件在本地的临时路径。
fileSizeNumber文件大小,单位为 byte。
startTimeNumber文件开始上传的时间戳。
totalDurationNumber上传总体耗时,单位为 ms。

key

String

当前上传任务的 key。

说明

addFile 时,是自动生成的。

oidString文件存储的 URI。
percentNumber当前上传总体进度百分比。
speedNumber文件上传的平均速度,单位为 kb/s。

status

Number

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

  • 1:正在运行

  • 2:取消运行

  • 3:暂停运行

  • 4:上传成功

  • 5:上传失败

type

'success' | 'error'

当前任务状态。取值如下:

  • success:成功

  • error:失败

uploadIdString可选,本次上传所使用的uploadId
extraObject当前状态的描述(随着生命周期不断变化)
extra.messageString描述性信息。
uploadResultObject上传成功之后返回的音视频 Meta 信息,封面信息等。详见属性详细说明 uploadResult
uploadResult 属性详细说明如下:
视频上传

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

属性类型描述
VidString视频 ID,vid 是视频在视频架构中的唯一 ID。
PosterUriString封面图 uri,当添加有截取封面信息的配置时返回。
SourceInfoObject视频源信息。
SourceInfo.BitrateNumber视频码率,单位:Kbps。
SourceInfo.DurationNumber视频时长,单位:秒。

SourceInfo.FileType

String

文件类型。取值如下:

  • video:视频。

  • audio:音频。

SourceInfo.FormatString文件格式。
SourceInfo.FpsNumber帧率。
SourceInfo.HeightNumber视频高度,单位为 px。
SourceInfo.WidthNumber视频宽度,单位为 px。
SourceInfo.SizeNumber视频文件大小,单位为 byte。

SourceInfo.StoreUri

String

视频源文件在 TOS 存储桶中的 URI。

注意

获取视频播放地址请不要使用这种方式访问。

SourceInfo.Md5String视频文件 md5 值。
SourceInfo.TosStorageClassString文件在对象存储中的存储类型。
SourceInfo.VideoStreamMetaObject视频流 meta 信息,当添加有获取 meta 信息的配置时返回。
VideoStreamMeta.DurationNumber视频时长,单位:秒。
VideoStreamMeta.WidthNumber视频宽度,单位为 px。
VideoStreamMeta.HeightNumber视频高度,单位为 px。
VideoStreamMeta.CodecString视频编码格式。
VideoStreamMeta.BitrateNumber视频流码率,单位:kbps
VideoStreamMeta.DefinitionString视频清晰度。
VideoStreamMeta.FpsNumber视频流帧率。
AudioStreamMetaObject音频流 meta 信息
AudioStreamMeta.CodeString音频编码格式。
AudioStreamMeta.DurationNumber音频时长,单位:秒。
AudioStreamMeta.SampleRateNumber音频采样率。
AudioStreamMeta.BitrateNumber音频码率,单位:Kbps
AudioStreamMeta.QualityString音频质量。

普通文件上传

属性类型描述
UriString源文件在 TOS 存储桶中的 URI,格式为 bucket/oid
ObjectMetaObject文件 meta 信息,当添加有获取 meta 信息的配置时返回。
ObjectMeta.Md5String文件 md5 值。
ObjectMeta.UriString与上层中的 Uri 一致。

error 事件

error 事件回调的参数如下所示:

属性类型描述
keyString标识本次上传任务的字符串,由 addFile 方法返回
codeNumber错误码,包含小程序原生的错误码
errorString具体错误,包含小程序原生的错误信息
messageString错误描述信息
typeString事件类型,固定为 error
stageNumber上传任务发生错误的阶段
statusCodeNumber可选,网络请求的状态码
oidString可选,文件的 URI。
uploadIdString可选,唯一的上传 ID。

错误码

详见上传 SDK 错误码