本文为您介绍如何使用 HarmonyOS NEXT 上传 SDK 将文件上传至 veImageX。

集成准备

环境要求

添加仓库

在项目根目录下创建 .ohpmrc 文件并配置 OpenHarmony 三方库中心仓和火山引擎仓库地址。

registry=https://ohpm.openharmony.cn/ohpm/
@vcloud:registry=https://artifact.bytedance.com/repository/byted-ohpm/
@bytedance:registry=https://artifact.bytedance.com/repository/byted-ohpm/
@ttnet:registry=https://artifact.bytedance.com/repository/byted-ohpm/

添加 SDK 依赖

在需要使用上传 SDK 的模块 /entry 下的 on-package.json5 文件中添加 SDK 依赖：

"dependencies": {
  "@bytedance/bduploader": "x.x.x"
}

基础功能

初始化 SDK

// 引入头文件
import { TTUploaderUtil} from '@bytedance/bduploader';

// 初始化 SDK，App 生命周期内只需初始化一次
if (this.mSDKInit == 0) {
  TTUploaderUtil.setEnableNativeLog(1); 
  TTUploaderUtil.setEnableNativeLog(1); //0: 禁用日志 1: 开启日志，建议 debug 阶段保持开启，便于排查问题。
  TTUploaderUtil.init(getContext(this).getApplicationContext());
  this.mSDKInit = 1;
}

创建上传实例

// 引入头文件
import {
TTImageUploader, 
TTUploaderUtil, 
UploadType, 
BDImageInfo, 
LogInfo, 
ImageInfoListener,
TTImageUploadNotifier
} from '@bytedance/bduploader';

// 创建 imageUploader 上传实例
this.imageUploader = new TTImageUploader(UploadType.InnerUploaderTypeImageX);

设置需要上传的文件

// @param num 需要上传的文件个数，最大值为 10
// @param path 需要上传的文件绝对路径数组
this.imageUploader.setFilePath(this.filePathArr.length, this.filePathArr);

设置鉴权

您需要在应用服务端通过 veImageX 服务端 SDK 签发临时上传凭证（accessKey、secretKey 和 Token），并下发给客户端，再设置给 SDK。鉴权参数说明及获取方式详见客户端上传说明，代码示例如下所示。

this.imageUploader.setTopAccessKey(this.accessKey); // 设置 AK
this.imageUploader.setTopSecretKey(this.secretKey); // 设置 SK
this.imageUploader.setTopSessionToken(this.sts2Token) // 设置 Token

设置服务 ID

通过指定服务 ID（即 serviceId）设置文件上传后的目标存储位置。服务相关说明详见新建服务。

this.imageUploader.setServiceID(this.serviceId);  // 设置服务 ID

设置上传域名和区域

// 如无特殊情况，请传入如下默认值
this.imageUploader.setUploadDomain("imagex.volcengineapi.com"); // 设置上传域名
this.imageUploader.setRegionName("cn-north-1"); // 设置上传区域

设置上传后文件存储路径

当上传完成，文件在 veImageX 的存储路径形式如下所示。

StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}

各参数说明如下表所示，更多参数说明详见名词解释，如 StoreKey。

支持以下三种存储路径设置方式。

// 方式一： 设置 storeKey
// 例如，文件的存储路径为 tos-cn-xxxx/testPrefix/test0.jpg。则 StoreKey 需指定为 testPrefix/test0.jpg
if (this.storeKeys.length > 0) {
  this.imageUploader.setFileStoreKeys(this.storeKeys.length ,this.storeKeys);
}

// 方式二：设置前缀、后缀
// 例如，文件的存储路径为 tos-cn-xxxx/testPrefix/6c6f96cf981ece3ac5b36fb059a5c390.jpg。则 FilePrefix 需指定为 testPrefix，FileExtension 需指定为 .jpg。
if (this.filePrefix) {
  this.imageUploader.setFilePrefix(this.filePrefix);
}

if (this.fileExtension.length > 0) {
  this.imageUploader.setFileExtension(this.fileExtension)
}

// 方式三：使用 md5 作为文件名
this.imageUploader.setEnableMd5StoryKey(this.enableMd5Key); // 是否使用 md5 作为文件名，默认值为 false

上传控制

// 开始或恢复上传
private async StartImageUploader(): Promise<void> {
  await this.imageUploader?.start();
}

// 暂停上传
private async stopImageUploader() : Promise<void>{
  await this.imageUploader?.stop();
}

// 终止上传
public async closeImageUploader(): Promise<void> {
  await this.imageUploader?.close();
  this.imageUploader = undefined;
}

设置回调

回调参数详见回调说明。

//设置回调
let listener = new UploaderImageListener(this.imageUploader, this);
this.imageUploader.setImageInfoListener(listener);

//监听回调
export class UploaderImageListener implements ImageInfoListener {
  private imageUploader?: TTImageUploader;
  private uploaderPage: UploaderPage;

  constructor(imageUploader: TTImageUploader,  uploaderPage: UploaderPage) {
    this.imageUploader = imageUploader;
    this.uploaderPage = uploaderPage;
  }
  onCancel(uploader:TTImageUploader ): void {
    hilog.info(0x0000, 'UploaderImageListener', '%{public}s', 'onCancel');
  }
  
  // 上传进度和上传状态回调。onNotify 详情请见 https://www.volcengine.com/docs/508/148786#_7-%E8%AE%BE%E7%BD%AE%E5%9B%9E%E8%B0%83
  async onNotify(what: number, info: BDImageInfo):  Promise<void> {
    hilog.info(0x0000, 'UploaderImageListener',
        'what=%{public}d, ' +
        'BDImageInfo:mTosKey:%{public}s,' +
        'mFileIndex:%{public}d,' +
        'progress: %{public}d,' +
        'mEncInfo:%{public}s,' +
        'errorCode:%{public}d,' +
        'errormsg:%{public}s' +
        'mMetaInfo:%{public}s',
      what,
      info.mImageTosKey,
      info.mFileIndex,
      info.mProgress,
      info.mEncryptionMeta,
      info.mErrorCode,
      info.mErrorMsg,
      info.mMetaInfo);
  }
  
   // 关键日志回调，您可将回调信息上传到您的服务器，可通过日志排查线上问题。
  // 不使用空实现即可。
  onLog(what:number, info:LogInfo):void {
    hilog.info(0x0000, 'UploaderImageListener', 'onLog:%{public}s', info);
  }
}

进阶功能

设置重名文件覆盖上传

您可以通过开启重名覆盖上传，使新上传文件在上传路径及文件名重复时覆盖同名旧文件。若不开启，则新文件上传失败。具体使用步骤如下所示：

1. 参考配置重名覆盖上传在 veImageX 控制台打开重名覆盖上传的功能开关。
2. 在 SDK 内开启覆盖上传，代码示例如下所示：

this.imageUploader.setEnableOverwrite(this.enableOverride); // 是否覆盖上传，默认值为 false

设置是否返回图片 meta 信息

如果您无需在上报阶段使 SDK 返回图片文件的 Meta 信息，建议您跳过图片 Meta 信息上报，以提升上传速度。

this.imageUploader.setEnableSkipMeta(this.skipMeta); // 是否返回图片信息，默认值为 false

设置自定义请求参数

调用 setServerParameter 设置自定义参数，如 appid（应用 ID）、did（设备唯一标识）、uid（用户唯一标识） 和 region （地域）等，以便您排查上传日志。代码示例如下所示：

// 例如："appid=123&did=123456&uid=12345&Region=xxx"
this.imageUploader.setServerParameter(this.serverParam); // 设置回调参数

自定义其他配置

上传 SDK 还支持设置使用分片上传的文件阈值、分片大小和并行上传的线程数，代码示例如下所示。

// 设置使用分片上传的文件阈值
// 若单个文件大小 > 阈值，则使用分片上传。单位为 byte，阈值的默认值为 1G。
if (this.SliceThreshold > 0) {
    this.imageUploader.setSliceThreshold(this.SliceThreshold);
}

// 设置分片大小，单位为 byte，默认值为 512KB。
if (this.sliceSize > 0) {
  this.imageUploader.setSliceSize(this.sliceSize);
}

// 设置需要同时上传多个文件时，并行上传的线程数，默认值为 1。
// 请根据实际情况适当调整并发量，但不建议取值过大，以免导致上传失败率提高。
if (this.socketNum > 0) {
  this.imageUploader.setSocketNum(this.socketNum);
}

// 设置 SDK 总建连超时时间，单位为秒，默认值为 300。 
if (this.timeoutSec > 0) {
    this.videoUploader.setSDKMaxRetryTimeout(this.timeoutSec);