You need to enable JavaScript to run this app.
导航

集成 Web 上传 SDK

最近更新时间2024.02.04 17:20:39

首次发布时间2021.02.23 10:42:28

JS 版上传 SDK 支持图片的上传,默认支持文件的批量上传、分片上传、并发上传和上传网关域名配置。以下将为您介绍 SDK 的集成、配置等具体操作内容。

SDK 集成

引入 SDK

支持以下两种引入 SDK 方式,您可根据实际需要任选其一。

npm install tt-uploader
   

初始化上传配置

import TTUploader from 'tt-uploader';
const ttUploader = new TTUploader({
    appId: xxx,      // 必填,应用 ID。在应用服务中创建的 AppID,质量监控等以该参数来区分业务方,务必正确填写
    userId: 'xxx',  // 必填,用户 ID。建议设置能识别用户的唯一标识 id,用于上传出错时排查问题,不要传入非 ASCII编码
    // 必填,图片上传相关配置
    imageConfig: {
        serviceId: 'xx',// 必填,服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
    }
});

说明

  • 如没有 AppID,请登录火山引擎控制台进入应用管理,创建应用后获取 AppID。
  • 如没有 ServiceID,请登录 veImageX 控制台进入服务管理,参考新建服务创建服务并获取 ServiceID。

添加上传文件

调用 addImageFile 方法,实现添加上传文件的代码示例如下所示:

说明

addImageFile 将返回所添加上传文件 key 值,用于文件的上传和取消上传等方法。

const fileKey = ttUploader.addImageFile({
    // 必填,待上传的Blob/File文件
    file: Blob,
    // 必填,从服务端拿到的token,token为一个对象类型,详见下方 stsToken 签名生成 sdk 说明
    stsToken: {
         AccessKeyId: "",
         SecretAccessKey: "",
         SessionToken: "",
         ExpiredTime: "",
         CurrentTime:"",
    }
});

stsToken 签名生成 sdk

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

说明

由于签名计算放在前端会暴露 AccessKey 和 SecretKey,我们把签名计算过程放在后端实现,即利用签名 SDK 生成临时的 AK、SK 等;前端通过 http 请求向后端获取签名结果,正式部署时请在后端加一层您自己网站本身的权限检验。

设置监听事件

设置监听事件,具体代码示例如下所示:

ttUploader.on("complete", (infor) => {
    console.log("complete");
    console.log(infor.uploadResult);
});

ttUploader.on("error", (infor) => {
    console.log(infor.extra);
});

ttUploader.on("progress", (infor) => {
    console.log(infor.percent)
});

详情请参考生命周期

开始上传

调用 start 方法,传入添加上传文件返回的key值,具体代码示例如下所示:

ttUploader.start(Key);

初始化配置

通用配置

配置属性可在实例化时传入,具体代码示例如下所示:

const ttUploader = new TTUploader({
    userId: "xxx",
    appId: 666,
    imageConfig: {
        serviceId: "xxx"
    }
});

各个配置及其对应作用如下表所示:

字段名类型是否必传描述
userIdString用户 ID,默认值为 null。用于进行单点追踪日志,定位某一个用户的日志,请设置一个唯一 ID。
appIdNumber应用 ID。用于定位某一条业务线的日志,默认值为 null。

region

String

上传地区。有以下三种取值:

  • cn-north-1:国内
  • ap-singapore-1:新加坡
imageConfigObject图片上传专用配置,默认值为 null。
imageHostString上传网关域名配置,各地区默认网关域名。
getSliceFuncFunction分片策略方法,返回分片大小值,回调入参一个参数为当前文件大小。默认为:当文件为 200M 以下时 5M 一片;当文件为 200M 以上时 10M 一片。
function(fileSize) { return fileSize > 200 * 1024 * 1024 ? 10 * 1024 * 1024 : 5 * 1024 * 1024 },分片值小于 2M 时,统一按 2M 分片。
useFileExtensionBoolean是否获取文件后缀名,开启由 SDK 读取文件后缀名作为 fileExtension 参数,以获取文件的存储 key。默认值为 false。

图片专用配置

示例如下所示:

imageConfig: {
    serviceId: "xxx"  //服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
}
字段名类型是否必传默认值描述
serviceIdStringnull服务 ID,您可进入服务管理创建服务后获取 serviceId 的值。

imagexEnableEncrypt

Boolean

false

是否开启全链路加密上传。取值如下所示:

  • true:开启加密上传,开启后,支持加密所有合法文件。
  • false:不开启

说明

您可参考最佳实践-全链路数据加解密 进行上传文件加解密全流程操作。

imagexEncryptKey

String

null

对称密钥,用于加密上传文件。您可选择自定义或由 SDK 随机生成后由回调下发。

  • 自定义:固定为 32 个字符长度的 ASCII 字符串;
  • SDK 随机生成:开启加密能力且不指定对称密钥时,SDK 内部将生成一个随机字符串,并通过 complete 回调下发。

注意

veImageX 无法感知对称密钥,则您需要自行对加密密钥的完整性和正确性负责。因您维护不当导致对称密钥用错或丢失,从而导致加密数据无法解密所引起的一切损失和后果均由您自行承担。

imagexPublicKey

String

null

如果业务强依赖 complete 回调中返回的图片 Meta 信息,则必填。

非对称加密公钥,用于加密对称密钥。请参考配置数据加密密钥在控制台获取。

说明

如果您强依赖 meta 信息,建议您通过调用查询图片 meta 信息接口获取。

注意

开启全链路加密之后,如果需要从 SDK 的 complete(上传完成)的回调中获取到加密图片的 Meta 信息,您需要额外引入 Encrypt 加密插件。

代码示例如下所示:

import TTUploader from 'tt-uploader';
import ImagexEncrypt from 'tt-uploader/dist/plugins/imagexEncrypt';
const ttUploader = new TTUploader({
    appId: xxx,      // 必填,应用 ID。在应用服务中创建的 AppID,质量监控等以该参数来区分业务方,务必正确填写
    userId: 'xxx',  // 必填,用户 ID。建议设置能识别用户的唯一标识 id,用于上传出错时排查问题,不要传入非 ASCII编码
    // 必填,图片上传相关配置
    imageConfig: {
        serviceId: 'xx',// 必填,服务 ID。请在 veImageX 控制台-服务管理查看并记录该值。
        imagexEnableEncrypt: true,
        imagexEncryptKey: 'KwvdQPHlu9MZk9eIZ4ZJAFoJM9ek4xaf',    // 可选
        // 加密场景下要获取图片Meta信息则必填
        imagexPublicKey: `-----BEGIN PUBLIC KEY-----
                          xxxxxxxxxxxxxxxxxxxxxxxx
                          xxxxxxxxxxxxxxxxxxxxxxxxx
                          -----END PUBLIC KEY-----`
    }
});
// 使用加密插件
ttUploader.use(new ImagexEncrypt());

方法

组件的方法及相关示例如下所示:

addImageFile(imageFileOption)

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

字段名类型是否必传默认值描述
fileBlob 或 Blob[]null上传的文件,传入 file 数组时可批量上传。
stsTokenObjectnull上传签名,token 是一个对象,包含AccessKeyId、SecretAccessKey、SessionToken、CurrentTime、ExpiredTime属性。
storeKeyString 或 String[]null上传文件的存储 key(仅支持[A-Za-z0-9-_./],不支持以 / 开头或结尾,不支持 / 连续出现),与 file 参数一一对应。默认使用随机生成的字符串作为存储 key。
serviceIdStringnull用于在添加文件时指定 serviceId,如果不指定,则本次上传文件到初始化配置 imageConfig 中指定的 serviceId。
prefixStringnull上传文件的存储 key(不支持以 / 开头或结尾,不支持 / 连续出现),指定时下发的存储 key 将为 prefix/{随机key}{fileExtension}。仅当未指定 storeKey 时生效。
fileExtensionStringnull指定文件扩展名,作为存储 key 的一部分(形如:.java, .txt, .png等)。仅当未指定 storeKey 时生效。

skipMeta

Boolean

false

是否返回图片 meta 信息。

说明

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

skipCommitBooleanfalse是否跳过上传成功后的上报阶段(可提高上传成功率,减少上传耗时)。如果指定为 true,则在控制台默认不展示该文件。

overwrite

Boolean

false

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

  • true:开启
  • false:不开启

注意

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

const key = ttUploader.addImageFile({
    file: Blob, // 上传文件的Blob对象
    stsToken: {
         AccessKeyId: "",
         SecretAccessKey: "",
         SessionToken: "",
         ExpiredTime: "",
         CurrentTime:"",
    },
});
console.log(key);  // 返回的文件 key 值,例如:file_1495442273603_999031

setServiceId(serviceId)

修改初始化配置 imageConfig 中的 serviceId,代码示例如下所示:

ttUploader.setServiceId('xxxxxxx');

start(key)

启动图片上传任务。如果上传被暂停,则再次调用此方法时将从断点处开始上传。你需要传入文件的 key 值,若不传参数,则将开始所有文件的上传。

说明

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

ttUploader.start();

removeFile(key)

移除某个待上传的文件(取消该文件的上传)。

说明

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

ttUploader.removeFile("file_1495442273603_999031");

cancel(key)

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

说明

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

ttUploader.cancel();

pause(key)

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

说明

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

ttUploader.pause();

restart(key)

恢复上传。传入文件的 key 值,如果不传参数,则将恢复所有文件的上传。

说明

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

ttUploader.restart();

生命周期

此处的生命周期是指上传某一个文件时候的生命周期,即一个上传过程的各个任务。

捕获某个生命周期,代码示例如下所示:

ttUploader.on("xxx", function(data) {
    console.log("xxx", data);
});

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

过程名称描述备注
preUpload获取图片上传信息初始化相关上传信息,比如 oid。
initUploadID初始化分片上传仅大文件上传时会触发,完成后得到上传所需的 uploadID。
progress图片上传进行中实时更新 percent(总体进度)。
complete图片上传完成部分已开获取分片权限的用户,在上传完成后可得到 ImageUri 等上传结果。

Returned Value

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

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

status

文件上传运行状态,支持以下取值:

  • 1:正在运行
  • 2:取消运行
  • 3:暂停运行
tasktask 队列实例
type当前任务状态,成功/失败

imagexEncryptKey

开启加密上传能力且不指定对称密钥时,该值表示 SDK 内部随机生成一个加密密钥。

注意

该密钥由您自行维护,veImageX 无法感知。您可在加载 SDK 使用该密钥对加密图片解密加载。

uploadResult

图片上传

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

错误码

错误码描述
1000001addFile 的 file 属性不是 Blob/File 的实例
1000002传入的 ststoken 有误
1001000apply 阶段请求失败-网络错误
1002000initUploadId 阶段请求失败-网络错误
1003000progress 阶段请求失败-网络错误
1003003上传文件读取失败,一般出现在上传中的文件被删除的情况下
1004000merge 阶段请求失败-网络错误
1005000commit 阶段请求失败-网络错误
100006请求过期或请求的签名时间来自未来,如果仅部分用户出现该问题,可能为系统时间不准导致
100009请求的 AK 不合法
100026错误的 STS or STS2,可能是多种错误,例如签名错误、过期等