You need to enable JavaScript to run this app.
导航
集成 HarmonyOS NEXT 上传 SDK
最近更新时间:2025.07.03 15:55:47首次发布时间:2024.09.04 14:02:53
我的收藏
有用
有用
无用
无用

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

集成准备

环境要求

类别

说明

鸿蒙系统版本

HarmonyOS Next Developer Beta2 及以上版本

开发工具

DevEco Studio

调试设备

HarmonyOS NEXT 上传 SDK 目前仅支持 arm64-v8a 架构(不支持 x86 模拟器),建议您使用真机调试使用

添加仓库

在项目根目录下创建 .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 下的 oh-package.json5 文件中添加 SDK 依赖:

说明

请参见 HarmonyOS NEXT 上传 SDK 发布历史获取 SDK 最新版本号。

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

声明权限

在需要使用上传 SDK 的模块 /entry 下的 module.json5 文件中声明权限:

"requestPermissions": [
    {
        "name": "ohos.permission.INTERNET"
    },
    {
        "name": "ohos.permission.GET_NETWORK_INFO"
    },
    {
        "name": "ohos.permission.MEDIA_LOCATION",
        "reason": "$string:network",
        "usedScene": {
            "when": "inuse"
        }
    },
    {
        "name": "ohos.permission.WRITE_MEDIA",
        "reason": "$string:network",
        "usedScene": {
            "when": "inuse"
        }
    },
    {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "$string:network",
        "usedScene": {
            "when": "inuse"
        }
    }
]

基础功能

初始化 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。鉴权参数说明及获取方式详见客户端上传说明,代码示例如下所示。

注意

如需使用重名文件覆盖上传,请确保您签发 上传凭证(此处以 Golang 为例)时已开启重名覆盖功能。

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

参数

含义

描述

BucketName

存储桶名称

您无需手动设置,此处会根据指定的服务 ID 自动生成。

FilePrefix

文件前缀

可选,路径字符串,支持多级路径,如 path/A/B/C

FileTitle

文件标题

可选,如果不手动设置,SDK 会自动生成 32 位字符串作为文件名。

FileExtension

文件后缀

可选。后缀需以. 开头,如 .png

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

// 方式一: 设置 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);
  }
}

进阶功能

设置重名文件覆盖上传

说明

  • 开启重名覆盖上传功能会存在较高的数据安全风险,建议非必要不开启。如需开启,建议您在客户端上传 STS 中限制上传文件 Storekey 的格式,以免您的存储资源受到污染。
  • 开启前,请确保您生成上传凭证时已添加重名覆盖上传的标识。

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

  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);