veImageX
veImageX
- 文档首页
veImageX客户端 SDK上传 SDKAndroid 上传 SDK进阶功能
文档反馈
问问助手本文档将为您介绍 veImageX 上传 SDK 的进阶能力。
设置云端储存 key
在文件上传完成后，文件在云端的存储路径形式如下所示：
StoreUri = {{BucketName}}/{{FilePrefix}}{{FileTitle}}{{FileExtension}}
各参数说明如下表所示：
参数 | 含义 | 描述 |
|---|---|---|
BucketName | 存储桶名称 | 接入方无需手动设置。 |
FilePrefix | 文件前缀 | 可选，路径字符串，支持多级路径（如 path/to/foo/bar/） |
FileTitle | 文件标题 | 可选，如果不手动设置，SDK 会自动生成 32 位字符串作为文件名。 |
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); mUploader.setFileStoreKeys(num, storeKeys);
例如：tos-cn-xxxx/testPrefix/test0.jpg，对应关系如下表所示：
字段 | 含义 | 说明 |
|---|---|---|
tos-cn-xxxx/ | 存储桶名称 | 接入方无需手动设置。 |
testPrefix/ | 文件前缀 | 可选。 |
test0 | 文件名 | 可选。若不手动设置，SDK 将自动生成一个 32 位字符串作为文件名。 |
.jpg | 文件后缀 | 可选。 |
设置重名文件覆盖上传
注意
- 重名文件：文件存储 key 相同
- 开启重名覆盖上传功能会存在较高的数据安全风险，建议非必要不开启。如需开启建议您在客户端上传 STS 中限制上传文件 Storekey 的格式，以免您的存储资源受到污染。
- 开启前，请确保您的上传 STS 签名（此处以 Golang 为例）已添加重名覆盖上传的标识。
您可以通过开启重名覆盖上传，使新上传文件在上传路径及文件名重复时覆盖同名旧文件。若不开启，则新文件上传失败。具体使用步骤如下所示：
- 参考配置重名覆盖上传在 veImageX 控制台打开重名覆盖上传的功能开关。
- 在组件内开启覆盖上传，代码示例如下所示：
mUploader.setEnableOverwrite(true); //开启文件重名覆盖上传
设置加密上传
说明
您可参考最佳实践-全链路数据加解密 进行上传文件加解密全流程操作。
您可通过在 SDK 开启加密上传并使用 AES Key （自定义或 SDK 随机生成）加密原始上传文件。使用非对称公钥 RSA Public Key 加密 AES Key，AES Key加密上传文件。加密完成后 SDK 上传加密数据至 veImageX 服务。上传 SDK 将 veImageX 返回的上传成功的文件 URI 及 meta 信息回调给业务 APP。具体代码示例如下所示：
注意
您需要对AES Key的完整性和正确性负责，因您维护不当导致AES Key用错或丢失，从而导致加密数据无法解密所引起的一切损失和后果均由您自行承担。
// 设置是否使用 全链路加密功能 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; } }
设置是否跳过上传成功后的上报阶段
如果您无需在 veImageX 控制台资源管理查看资源列表，建议您跳过资源上传成功后的上报阶段，以提升上传速度，减少上传耗时。跳过上报阶段后，控制台不再显示上传成功的资源文件，建议您调用 GetImageUploadFiles 接口查看服务下上传文件。
注意
若您需要使用智能审核，请勿跳过资源上传成功后的上报阶段，否则系统将无法触发图片审核。
// 设置是否跳过上传成功后的上报阶段，默认值为 true mUploader.setEnableCommitUpload(false);
设置是否返回图片 meta 信息
如果您无需在上报阶段使 SDK 返回图片 meta 信息，建议您跳过图片 meta 信息上报，以提升上传速度。
注意
若您需要使用智能审核，请勿跳过图片 meta 信息上报，否则系统将无法触发图片审核。
// 设置是否返回图片 Meta 信息，默认值为 false mUploader.setEnableSkipMeta(true);
设置是否强制获取图片 meta 信息
文件上传成功后，是否强制获取图片 meta 信息。默认值为 false。取值如下：
true：强制获取，即返回图片 meta 信息。false：不强制获取，即不返回图片 meta 信息。
mUploader.setEnableForceMeta(true);
说明
- 该方法优先级高于 setEnableSkipMeta。
- 如果图片 meta 信息获取超时或失败，接口报错，文件上传失败。
设置文件的 Content-Type
您可自定义上传文件的 Content-Type，如 gif 图片，指定其 Content-Type 为 image/gif。您可参考不同格式对应的常见 Content-Type 值。
说明
若您上传的目标服务已配置服务维度的 Content-Type 白名单限制。那么，此处设置的文件 Content-Type 需在白名单内，否则文件将无法成功上传。
// 与上传的文件个数保持一致 int num = 2; // 确保与上传的文件数组一一对应，用于准确指定各文件的 Content-Type。 String[] contentTypes = new String[num]; contentTypes[0] = "image/png"; contentTypes[1] = "image/png"; mUploader.setSpecifiedContentType(num, contentTypes);
设置自定义请求参数
调用 setServerParameter 设置自定义参数，如 appid（应用 ID）、did（设备唯一标识）、uid（用户唯一标识） 和 region （地域）等，以便您排查上传日志。参数示例如下所示：
// 设置自定义请求参数的字符串，例如："appid=123&did=123456&uid=12345&Region=xxx" public void setServerParameter(String value)
设置 HttpDns 重试
说明
- 上传 SDK 云控配置中默认开启 HttpDns 重试功能，如开启了 SDK 云控，且不想使用 HttpDns 重试功能，请通过云控配置关闭。
- 使用 1.45.2.7 版本时必须调用
BDHttpDns.getInstance().init(context.getApplicationContext());进行初始化，在 1.45.3.7 及更高的版本中无需调用。
为了避免因遭遇 LOCAL DNS 劫持导致的文件上传失败，您可开启 HttpDns 重试功能，来确保文件能够正常上传。代码示例如下所示：
// 1. 初始化 httpdns BDHttpDns.getInstance().init(context.getApplicationContext()); Env.init(new Config.Builder() ...); // 2. 对 uploader 实例开启 httpdns 重试功能，取值请均指定为 1 mUploader.setEnableExternDNS(1); mUploader.setEnableHttpDnsRetry(1); // 3. 设置文件的上传重试次数，取值请务必设置为大于或等于 2，默认值为 3。 mUploader.setFileRetryCount(2);
设置云控
说明
自 1.45.3.7 版本起支持。
云控指通过控制台参数的配置，对客户端 SDK 进行配置下发，适用于业务需要灵活修改配置参数的场景。控制台配置操作指南参看 SDK 配置下发。
云控功能默认不开启，如果需要开启则需在 SDK 初始化中添加如下代码：
// SDK 初始化 Env.init(new Config.Builder() ... // 开启云控 .setOpenUploadCloudControl(true) // 如果需要设置DeviceId 那么可以在 LogConfig中配置 .setLogConfig(gtLogConfig(context)) ... .build());
自定义上传域名
说明
自 1.46.2.12 版本起支持。
SDK 支持配置自定义的上传线路，veImageX 为每个服务分配两个上传域名，域名格式参考上传域名，参考示例如下：
BDImageXUploader mUploader = new BDImageXUploader(); mUploader.setCustomTosHost("{serviceID}.xxx.com");
其他配置
上传 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)