You need to enable JavaScript to run this app.
导航
集成小程序上传 SDK
最近更新时间:2024.05.17 17:01:02首次发布时间:2023.08.09 11:00:52

本文为您介绍小程序版本上传 SDK,支持微信小程序、抖音小程序和 uni-app 开发框架。

适用版本

本文档仅适用于 TTSDK 2.0.0 及以上的版本,其他版本请参考小程序上传 SDK(旧版)

说明

您可通过上传 SDK 发版历史查看各版本更新点。

前提条件

注意事项

  • veImageX 同时提供了素材资源托管与图像处理两类服务,您可根据实际需要指定上传文件存储服务类型。两种服务区别如下:
    • 素材托管服务:支持任意合法资源的上传和托管;
    • 图像处理服务:支持任意合法资源的上传和托管,还支持对图像文件执行图像实时处理。
  • 为了提高小程序平台大文件上传成功率,当上传文件大小大于 10M 时,SDK 将默认对大文件进行分片上传,每个分片大小默认为 5M。
  • 当使用 uni-app 集成小程序上传 SDK 时,因平台限制,仅在小程序平台支持分片上传,对于 Android 和 iOS 原生平台,如您需要进行分片上传,建议您集成原生的 Android / iOS 上传 SDK,否则可能会影响大文件的上传质量。

接入准备

获取上传签名

上传前需要从服务端获取上传 STS 临时访问凭证,签名算法由服务端接入,接入方法请参考以下服务端各生成上传凭证文档:

说明

由于签名计算放在前端会暴露 AccessKey 和 SecretKey,为了保障您的信息安全,避免上传资源受到污染。我们将签名计算过程放在后端实现(利用签名 SDK 生成一对临时的 AKSK),前端会向业务服务端获取签名结果,正式部署时请在后端加一层您自身网站本身的权限检验。

添加域名白名单

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

字段名内容

request 合法域名

  • https://imagex.volcengineapi.com
  • https://mcs.zijieapi.com
  • https://tos-lf-x-tob.bytecdn.cn
  • https://tos-lq-x-tob.bytecdn.cn
  • https://tos-hl-x-tob.bytecdn.cn

uploadFile 合法域名

  • https://tos-lf-x-tob.bytecdn.cn
  • https://tos-lq-x-tob.bytecdn.cn
  • https://tos-hl-x-tob.bytecdn.cn

安装 SDK

使用 npm 方式引入 SDK,具体代码示例如下所示:

npm install tt-uploader-miniprogram

集成 SDK

您可参考以下代码示例,配置回调监听并快速将文件上传至指定服务 ID 对应的 veImageX 服务中。

import TTUploader from 'tt-uploader-miniprogram';
// 初始化uploader
const uploader = new TTUploader({
    userId: 'volcengine-user1',  // 必填,用户 ID。自定义,建议设置能识别用户的唯一标识 id,用于上传出错时排查问题,不要传入非 ASCII编码
    appId: 78**27,             // 必填,应用 ID。在应用服务中创建的 AppID,质量监控等以该参数来区分业务方,务必正确填写
    imageConfig: {
        serviceId: 'hj****7f' // 必填,服务 ID。请在 veImageX 控制台-服务管理查看并记录该值
    }
});
// 设置监听事件
uploader.on('error', (info) => {
    console.log('上传失败', info)
})
uploader.on('progress', (infor) => {
    console.log('上传进度:', infor.percent)
});
uploader.on('complete', (info) => {
    console.log('上传成功', info)
})
// 添加上传文件
const key = uploader.addImageFile({
   path: '',      // 文件临时路径,从 chooseMedia 回调中获取
   size: 1234,    // 文件大小,从 chooseMedia 回调中获取
   // 从服务端获取到的临时访问凭证,请参考【接入准备-获取上传签名】说明
   stsToken: {
       "CurrentTime":"2023-03-31T07:47:14.866Z",
       "ExpiredTime":"2023-05-30T07:47:14.866Z",
       "SessionToken":"STS2****In0=",
       "AccessKeyId":"AKTPZDM1***iNTU5ODg",
       "SecretAccessKey":"aNXEA8uvC***Pqg=="
   },
   fileExtension: '.png'
});
// 开始上传
uploader.start(key)

初始化 SDK

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

const uploader = new TTUploader({
    userId: 'Test1',  //必填,自定义用户 ID,用于定位某用户的日志。
    appId: 67**23,  //必填,应用 ID,用于定位某业务应用的日志。
    imageConfig: {  //必填,图片上传配置。
        serviceId: 'hi****2t'  //必填,服务 ID,用于指定文件上传所在服务。
    }
});

您可参考下表完成以下配置,各配置具体说明如下表所示:

字段名类型是否必传默认值描述
userIdStringnull用户 ID。用于进行单点追踪日志,定位某一个用户的日志,请设置一个唯一 ID。

appId

Number

null

应用 ID。用于定位某一条业务线的日志。

  • 您可以登录 veImageX 控制台的应用管理,查看账号下已创建应用的应用 ID。
  • 您可以通过调用 GetImageXQueryApps 接口获取账号下已创建的全部应用 ID。
imageConfigObjectnull图片上传专用配置,默认值为 null。详情请参考 imageConfig

useFileExtension

Boolean

false

是否获取文件后缀名,取值如下所示:

  • true:获取,由 SDK 读取文件后缀名作为 fileExtension 参数,以获取文件的存储 key。
  • false:不获取。
uploadTimeoutNumber30min上传文件请求的超时时间,单位为 ms。示例为 1000 * 60 * 30
gatewayTimeoutNumber5min网关请求的超时时间,单位为 ms。示例为 1000 * 60 * 5

imageConfig

字段名类型是否必传默认值描述

serviceId

String

null

服务 ID。

  • 您可以登录 veImageX 控制台的服务管理,查看已创建图片服务的服务 ID。
  • 您可以通过调用 GetAllImageServices 接口获取账号下已创建的全部 服务 ID。

功能说明

addImageFile(imageFileOption)

添加上传图片文件,返回当前文件的 key 值(上传和取消上传等使用该值)。传入的 imageFileOption 配置如下表所示:

字段名类型是否必传默认值描述
pathStringnull上传文件的临时路径
sizeNumbernull上传文件的大小
stsTokenObjectnull上传签名,token 是一个对象,包含 AccessKeyId、SecretAccessKey、SessionToken、CurrentTime、ExpiredTime 属性。
serviceIdStringnull指定的上传文件服务存储。不指定时则使用初始化配置 imageConfig 中指定的 serviceId
storeKeyStringnull指定的上传文件存储 key。仅支持[A-Za-z0-9-_./],不支持以/开头或结尾,不支持/连续出现, 与 file 参数一一对应。默认使用随机生成的字符串作为存储 key。

prefix

String

null

仅当未指定 storeKey 时生效。
指定的上传文件路径(不支持以 / 开头或结尾,不支持 / 连续出现)。指定时下发的存储 key 为 prefix/{随机key}{fileExtension}

fileExtension

String

null

仅当未指定 storeKey 时生效。
指定的上传文件扩展名,作为存储 key 的一部分(形如:.java, .txt, .png等)。指定时下发的存储 key 为 prefix/{随机key}{fileExtension}

skipMeta

Boolean

false

是否获取图片 meta 信息,取值如下所示:

  • true:获取
  • false:(默认)不获取

说明

获取 meta 并返回对应的 meta 信息,如果 meta 获取超时或失败,则对应的 meta 信息为空。

skipCommit

Boolean

false

是否跳过上传成功后的上报阶段(提高上传成功率,减少上传耗时)。

  • true:跳过上传文件上报,控制台则默认不展示该文件。
  • false:(默认)不跳过上传文件上报。

overwrite

Boolean

false

是否开启重名覆盖上传,文件存储 key 相同时则为重名。开启后,新上传文件在上传路径及文件名重复时覆盖同名旧文件。若不开启,则新文件上传失败。取值如下所示:

  • true:开启
  • false:不开启

注意

开启前,请确保您的上传 STS 签名已添加重名覆盖上传的标识。

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

const key = ttUploader.addImageFile({
    path: '',      // 上传文件临时路径
    size: ,    // 上传文件大小
    stsToken: {
        AccessKeyId: "",
        SecretAccessKey: "",
        SessionToken: "",
        ExpiredTime: "",
        CurrentTime:"",
    },
    fileExtension: '.png'  //指定上传文件扩展名
});
console.log(key);  // 返回的文件 key 值,例如:file_1495442273603_999031

start(key)

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

说明

您可从 addImageFile 方法返回值中获取 key 值。

uploader.start();

pause(key)

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

说明

您可从 addImageFile 方法返回值中获取 key 值。

uploader.pause('file_1495442273603_999031');

restart(key)

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

说明

您可从 addImageFile 方法返回值中获取 key 值。

uploader.restart();

cancel(key)

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

说明

您可从 addImageFile 方法返回值中获取 key 值。

uploader.cancel();

事件说明

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

事件名称描述说明
progress文件上传进行中文件上传过程中会多次触发,可用于标识文件上传进度。会实时更新 percent,即总体进度。
complete文件上传完成文件上传成功时触发,标识一个上传任务结束。部分已开获取分片权限的用户,在上传完成后可得到 ImageUri 等上传结果。
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 事件回调参数如下表所示。

属性类型描述
percentNumber整体上传进度(百分比),取值范围为[0, 99]之间的整数,当complete事件触发后才认为进度为 100。
totalSizeNumber上传文件的总体大小,单位为 byte
sentSizeNumber此时已发送的字节数,单位为 byte
keyString标识本次上传任务的字符串,由 addFile 方法返回
oidString文件存储的 URI
sliceIndexNumber可选,分片上传的场景下,标识此索引的分片上传完成
uploadIdString可选,分片上传的场景下,标识此次上传的唯一 ID

complete 事件

complete事件回调参数如下表所示。

字段名称类型描述
filePathString文件在本地的临时路径
fileSizeNumber文件大小,单位为 byte
startTimeNumber文件开始上传的时间戳
totalDurationNumber上传总体耗时,单位为 ms
keyString当前上传任务的 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上传完成后的图片信息,包括 uri 等,见下方详细说明

uploadResult

字段名称类型描述
ImageUriString图片的 URI,格式为 bucket/oid
ImageWidthNumber图片宽度
ImageHeightNumber图片高度
ImageMd5String图片数据的 md5 值
FileNameString文件名,与 ImageUri中的 oid 部分一致
UriString与 ImageUri 一致

error 事件

error 事件回调参数如下表所示。

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

错误码说明

错误码描述
100006请求过期或请求的签名时间来自未来,如果仅部分用户出现该问题,可能为用户系统时间不准导致。
100026错误的 STS2,可能是多种错误,例如签名错误、过期等。
100013权限问题,ak sk 没有绑定策略或者 action 不对。
100009请求的 AK 不合法。
1000001addFile 的 file 属性不是 Blob/File 的实例。
1000002StsToken 格式错误,此类错误发生的原因为:传入的Object字段缺失。
1001000申请上传域名阶段错误。
1002000初始化上传时发生错误。
1003000文件上传阶段发生错误。
1003003上传文件读取失败,一般出现在上传中的文件被删除的情况下。
1004000文件分片合并阶段错误。
1005000完成上传,获取媒体信息错误。