本文档将为您介绍 veImageX 上传 SDK 的进阶能力。

1. 设置云端储存 key

在文件上传完成后，文件在云端的存储路径形式如下所示：

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

各参数说明如下表所示：

支持以下三种设置云端存储路径方式，您可根据实际业务情况，任选其一。

/**
  * 自定义上传文件的存储 key
 *
  *  @param num 图片个数
  *  @param storeKeys 存储 key 数据
  */
public void setFileStoreKeys(int num, String[] storeKeys); 

// 例 1，云端的存储路径：tos-cn-xxxx/testPrefix/test0.jpg
int num = 1;
String[] storeKeys = new String[num];
storeKeys[0] = "testPrefix/test0.jpg";

// 注意先 setFilePath，再 setFileStoreKeys; 
// 使用 MediaDataReader 同理， 详见快速开始 https://www.volcengine.com/docs/508/148786#_3-%E8%AE%BE%E7%BD%AE%E8%A6%81%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6
// mImageXUploader.setFilePath(num, path);
mImageXUploader.setFileStoreKeys(num, storeKeys);
 

// 例，云端的存储路径：tos-cn-xxxx/volc/6c6f96cf981ece3ac5b36fb059a5c390.jpg 
// 其中文件名 6c6f96cf981ece3ac5b36fb059a5c390 为随机生成。

// 设置前缀，可选
mUploader.setFilePrefix("volc"); 
// 设置后缀，可选，需要以 . 开头
mUploader.setFileExtension(".jpg");

// 例，云端的存储路径：tos-cn-xxxx/volc/6c6f96cf981ece3ac5b36fb059a5c390.jpg

// 使用文件的 md5 作为文件名
mUploader.setEnableMd5StoryKey(true)
// 设置前缀，可选
mUploader.setFilePrefix("volc"); 
// 设置后缀，可选，需要以 . 开头
mUploader.setFileExtension(".jpg");

例如：tos-cn-xxxx/testPrefix/test0.jpg，对应关系如下表所示：

2. 设置重名文件覆盖上传

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

1. 参考配置重名覆盖上传在 veImageX 控制台打开重名覆盖上传的功能开关。

2. 在组件内开启覆盖上传，代码示例如下所示：

mUploader.setEnableOverwrite(true) //开启文件重名覆盖上传

3. 设置加密上传

您可通过在 SDK 开启加密上传并使用 AES Key （自定义或 SDK 随机生成）加密原始上传文件。使用非对称公钥 RSA Public Key 加密 AES Key，AES Key加密上传文件。加密完成后 SDK 上传加密数据至 veImageX 服务。上传 SDK 将 veImageX 返回的上传成功的文件 URI 及 meta 信息回调给业务 APP。具体代码示例如下所示：

// 设置是否使用 全链路加密功能  option > 0 使用，默认关闭
public void setEnableEnd2EndEncryption(int option)

// 设置 RSA 公钥, 用于加密对称密钥。请从控制台配置和获取。
// 可选(当上传后不需要 ImageX 服务端进行处理时，可以不填。上传需要 commit上报阶段或者需要返回 meta信息时必填)
// 上传默认获取 meta，可通过 mUploader.setEnableSkipMeta(true); 关闭获取 meta
public void setEnd2EndEncryptionPublicKey(String key)

// 设置 AES key，即对称密钥，用于加密上传文件。支持 SDK 随机生成和自定义
// 您可以选择不设置，上传 sdk 将自动生成，在上传成功后经回调返回具体内容
// 如果您需自定义密钥内容，需为 32 位字符串，并经 base64 编码之后传入
public void setEnd2EndEncryptionAESKey(String key)

// 回调参数新增加密信息
public class BDImageXInfo {
    public String mImageTosKey;
    public int mFileIndex = -1;
    public long mProgress;
    public long mErrorCode;
    public String mMetaInfo;
    public String mEncryptionMeta;
    // 新增信息
    public BDImageXE2EEncryptionInfo mEnd2EndEncryption;

public class BDImageXE2EEncryptionInfo {
    public String mAESKey;
    public String mRSAKey;
    public String mAESIV;

    public BDImageXE2EEncryptionInfo(String aesKey, String rsaKey, String iv) {
        mAESKey = aesKey; // 由您自己保存，用于解密加载。
        mRSAKey = rsaKey;
        mAESIV  = iv;
    }
}

4. 设置是否跳过上传成功后的上报阶段

如果您无需在 veImageX 控制台资源管理查看资源列表，建议您跳过资源上传成功后的上报阶段，以提升上传速度，减少上传耗时。

// 设置是否跳过上传成功后的上报阶段，默认值为 true
mUploader.setEnableCommitUpload(false); 

5. 设置是否返回图片 Meta 信息

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

// 设置是否返回图片 Meta 信息，默认值为 false
mUploader.setEnableSkipMeta(true);

6. 设置文件的 Content-Type

您可自定义上传文件的 Content-Type，如 gif 图片，指定其 Content-Type 为 image/gif。您可参考不同格式对应的常见 Content-Type 值。

// 与上传的文件个数保持一致
int num = 2; 
// 确保与上传的文件数组一一对应，用于准确指定各文件的 Content-Type。
String[] contentTypes = new String[num];
contentTypes[0] = "image/png";
contentTypes[1] = "image/png";

mUploader.setSpecifiedContentType(num, contentTypes);

7. 设置自定义请求参数

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

// 设置自定义请求参数的字符串，例如："appid=123&did=123456&uid=12345&Region=xxx"
public void setServerParameter(String value)

8. 其他配置

上传 SDK 还支持分片上传等功能，您可以设置分片大小、开启并行上传的线程数等能力。具体操作代码示例如下所示：

// 设置进行分片上传的阈值
// 单张图片大小 > 阈值则走分片上传，否则走直传，单位 byte，默认值 1G
public void setSliceThreshold(int value)

// 设置单张图片并行上传的线程数，只有走分片上传的情况才生效，默认值 1
public void setSocketNum(int num)  

// 分片上传设置分片大小，单位 byte，默认值 512 * 1024；
public void setSliceSize(int size)

// 设置并行上传的文件数（上传多张图片的情况），
// 建议设置的最大并行数，应该是小于等于传入的图片数目。默认值 1
public void setMaxConcurrentFileNum(int num)

// 单个分片传输超时，单位 s，默认 40
public void setRWTimeout(int timeOut) 

// 总的建联超时，单位 s，默认 70
public void setMaxFailTime(int maxTime)

// 系统 socket 单次读写超时，单位 s，默认 10
public void setTranTimeOutUnit(int tranTimeOutUnit)

// 分片重试次数，默认值 2
public void setSliceReTryCount(int retryCount) 

// 文件级别的重试次数，默认值 3
public void setFileRetryCount(int retryCount)

// 开启 https，设置 1 为全开启
public void setEnableHttps(int isEnableHttps)