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

设置云端储存 key

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

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

各参数说明如下表所示：

具体操作代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 云端的存储路径：tos-cn-xxxx/testPrefix/test0.jpg
    // 为文件设置 storeKey
    storeKeys: storeKeys: ["testPrefix/test0.jpg"],
    ...
)

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

设置重名文件覆盖上传

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

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

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
);
BDImageXUploader uploader = await initImageXUploader(options);

// 开启覆盖
await uploader.setEnableOverwrite(true);

设置加密上传

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

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

BDImageXUploader uploader = await initImageXUploader(options);

// 设置是否使用 全链路加密功能  true 使用，默认false
await uploader.setEnableEnd2EndEncryption(true);

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


// 回调参数新增加密信息 参考上文 BDImageXUploadInfo

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

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

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

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

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

设置文件的 Content-Type

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

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    specifiedContentType: ["image/png"],
);

设置自定义请求参数

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

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 设置自定义请求参数的字符串，例如："appid=123&did=123456&uid=12345&Region=xxx"
    serverParameter: "appid=123&did=123456&uid=12345&Region=xxx",
);

设置 HttpDns 重试

为了避免因遭遇 LOCAL DNS 劫持导致的文件上传失败，您可开启 HttpDns 重试功能，来确保文件能够正常上传。代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 1. 设置文件的上传重试次数，取值请务必设置为大于或等于 2，默认值为 3。
    fileRetryCount: 2,
);

BDImageXUploader uploader = await initImageXUploader(options);

// 2. 对 uploader 实例开启 httpdns 重试功能
await uploader.setEnableHttpDNS(true);

设置云控

云控指通过控制台参数的配置，对客户端 SDK 进行配置下发，适用于业务需要灵活修改配置参数的场景。控制台配置操作指南参看 SDK 配置下发。
具体使用参考初始化 SDK 中 useImageXCloudControl 字段的使用。

其他配置

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

ImageXUploaderOptions options = ImageXUploaderOptions(
    ...
    // 设置进行分片上传的阈值
    // 单张图片大小 > 阈值则走分片上传，否则走直传，单位 byte，默认值 1G
    sliceThreshold: 2 * 1024 * 1024,
    // 设置单张图片并行上传的线程数，只有走分片上传的情况才生效，默认值 1
    socketNum: 3,
    // 分片上传设置分片大小，单位 byte，默认值 512 * 1024；
    sliceSize: 512 * 1024,
    // 设置并行上传的文件数（上传多张图片的情况），
    // 建议设置的最大并行数，应该是小于等于传入的图片数目。默认值 1
    maxConcurrentFileNum: 2,
    // 单个分片传输超时，单位 s，默认 40
    rwTimeout: 30,
    // 系统 socket 单次读写超时，单位 s，默认 10
    tranTimeout: 15,
    // 分片重试次数，默认值 2
    sliceRetryCount: 3,
    // 文件级别的重试次数，默认值 3
    fileRetryCount: 4,
    
);