以下为您介绍 iOS 上传 SDK 的进阶能力。

1. 设置云端存储 Key

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

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

各参数说明如下表所示：

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

#import <TTSDK/BDFileUploaderHeader.h>

- (void)initImageXUploaderClient {
    ......
    
    [self.imageXUploadClient setStoreKeys:<#NSArray<NSString * _Nonnull>#>]; 
    // [self.imageXUploadClient setStoreKeys:@[@"testPrefix/test0.jpg"]]; 
    
    ......

} 

#import <TTSDK/BDFileUploaderHeader.h>

- (void)initImageXUploaderClient {
    ......
    
    // YES 开启，默认关闭
    // 当开启此开关后，SDK在上传前计算文件的 MD5 值
    [self.imageXUploadClient setEnableMd5StoreKey:YES]; 

    // 按需设置 filePreix: 不能以 / 结尾
    [self.imageXUploadClient setFilePrefix:<#fileprefix#>];

    // fileExtension 必需，以 . 开头，例： .JPG, .PNG
    [self.imageXUploadClient setFileExtension:<#fileextension#>];
        
    ......

}

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

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

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

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

[self.imageXUploadClient setEnableOverwrite:<#BOOL#>];

3. 设置加密上传

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

[self.imageXUploadClient setE2EEncInfoDict:@{
    /**
     * 是否加密，@1：加密，@0 不加密
     */
     BDFileUploadE2EEncOption: @1,
    /**
    设置 RSA 公钥, 用于加密对称密钥。请从控制台配置和获取。
    可选(当上传后不需要 ImageX 服务端进行处理时，可以不填。上传需要commit上报阶段或者需要返回meta信息时必填)
    注意 public key 一般是多行文本:
    NSString *e2ePublicKey = @"-----BEGIN PUBLIC KEY-----\n"
    @"MIICIjANX***AwEAAQ==\n"
    @"-----END PUBLIC KEY-----";
     */
    BDFileUploadE2EEncPublicKey: <#NSString *#>,
    /**
     设置 AES key，即对称密钥，用于加密上传文件。支持 SDK 随机生成和自定义
     您可以选择不设置，上传 sdk 将自动生成，在上传成功后经回调返回具体内容
     如果您需自定义密钥内容，需为 32 位字符串，并经 base64 编码之后传入。
     举例：
     NSString *keyRaw = @"abcdefghijklmnopqrstuvwxyz123456";
     NSData *data = [keyRaw dataUsingEncoding: NSUnicodeStringEncoding];
     NSString *key = [NSStringUtil base64StringFromData:data length:[data length]];
     */
    BDFileUploadE2EEncAESKey: <#NSString *#>,
}];

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

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

[imageXUploadClient setUploadConfig:@{
    // 设置是否跳过上传成功后的上报阶段，设置为 0
    BDFileUploadEnableCommitUpload:@(0),
}];

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

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

// 设置是否返回图片 Meta 信息。
// 取值如下：1 跳过，不返回 meta 信息；0 不跳过，返回 meta 信息。
// 默认值为 0。
[imageXUploadClient setUploadConfig:@{
    // 这里设置为 1，上传成功后不会返回 meta 信息 
    BDFileUploadSkipMeta:@(1),
}];

6. 上传 LivePhoto

支持向 veImageX 服务端上传 LivePhoto 图片，上传的图片可以通过 BDWebImage 进行加载并以苹果官方 LivePhoto 的效果渲染显示。SDK 提供了一个工具类BDImageXLivePhotoUtil用于在上传 LivePhoto 前先进行打包处理或制作 ，由该工具类打包后，再按照上传流程完成上传。具体流程如下所示：

1. LivePhoto 打包，支持直接打包 PHLivePhoto 和分别打包图片与视频两种方式。

/// 打包一个 LivePhoto 图片为 ImageX 服务端规定格式
/// - 参数:
///   - livp: PHLivePhoto .
///   - tile: livePhoto 图片的标题.
///   - completion: 打包完成之后的回调
/// 注意: 必须在 completion 回调中将打包后的文件 copy 到自己的目录中，供上传时使用，否则当 completion 回调完成时，打包过的文件将会被自动删除
- (void)archiveLivePhoto:(PHLivePhoto *)livp
                   title:(NSString *)title
              completion:(BDImageXLivePhotoArchiveCompletionHandler)completion API_AVAILABLE(ios(9.1));
  

/// 打包一张图片+一张视频成为 LivePhoto
/// - Parameters:
///   - image: 图片文件路径
///   - image: 视频文件路径
///   - tile: livePhoto 图片的标题.
///   - completion: 打包完成之后的回调
/// 注意: 必须在 completion 回调中将打包后的文件 copy 到自己的目录中，供上传时使用，否则当 completion 回调完成时，打包过的文件将会被自动删除
- (void)archiveImage:(NSString *)image
               video:(NSString *)image
           fileTitle:(NSString *_Nullable)title
          completion:(BDImageXLivePhotoArchiveCompletionHandler)completion;
  

2. 初始化用于 LivePhoto 上传的实例
3. 设置上传其他配置，例如加密上传/覆盖上传等。
4. 开始上传。

具体代码示例如下所示。

// 1. 从相册读取 LivePhoto 
PHLivePhoto *livePhoto = ....;

// 2. 打包 LivePhoto 
BDImageXLivePhotoUtil *livePthoUtil = [[BDImageXLivePhotoUtil alloc] init];
[livePthoUtil archiveLivePhoto:<#PHLivePhoto *#> title:<#NSString *#> completion:^(NSError  _Nullable error, NSString * _Nullable path, BOOL * const isCopyCompleted) {
// 3. 打包完成
    if (error) {
        // 3.a. 打包失败，不能继续进行
        NSLog(@"archive livephoto error: %@", error);
        return;
    } else {
        // 3.b. 打包成功，先拷贝到工作目录下
        [self copyFile:path toPath:dstPath completion: ^{
            // 3.b.1 拷贝完成，执行上传流程。
            *isCopyCompleted = YES；// 拷贝完成后将 isCopyCompleted 置位 YES
            // 3.b.2 初始化上传实例
            BDImageXUploaderClient *imageXUploadClient = [[BDImageXUploaderClient alloc] initWithFilePaths:<#arrary#>];
            self.imgeXUploadClient = imageXUploadClient;
            // 3.b.3 设置 Options 
            ....
            [self.imageXUploaderClient start];
        }];
        
    }
}];
  

// 1. 从相册读取 LivePhoto 
PHLivePhoto *livePhoto = ....;

// 2. 打包 LivePhoto 
BDImageXLivePhotoUtil *livePthoUtil = [[BDImageXLivePhotoUtil alloc] init];
[livePthoUtil archiveImage:imagePath video:videoPath fileTitle:title completion:^(NSError * _Nullable error, NSString * _Nullable path, BOOL * _Nonnull isCopyCompleted) {
// 3. 打包完成
    if (error) {
        // 3.a. 打包失败，不能继续进行
        NSLog(@"archive livephoto error: %@", error);
        return;
    } else {
        // 3.b. 打包成功，先拷贝到工作目录下
        [self copyFile:path toPath:dstPath completion: ^{
            // 3.b.1 拷贝完成，执行上传流程。
            *isCopyCompleted = YES；// 拷贝完成后将 isCopyCompleted 置位 YES
            // 3.b.2 初始化上传实例
            BDImageXUploaderClient *imageXUploadClient = [[BDImageXUploaderClient alloc] initWithFilePaths:<#arrary#>];
            self.imgeXUploadClient = imageXUploadClient;
            // 3.b.3 设置 Options 
            ....
            [self.imageXUploaderClient start];
        }];
    }
}];
  

7. 设置文件的 Content-Type

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

// 确保与上传的文件数组一一对应，用于准确指定各文件的 Content-Type。
NSMutableArray *temp = @[].mutableCopy;
[temp addObject:@"image/png"];
[temp addObject:@"image/png"];
[temp addObject:@"image/png"];

[self.imageXUploadClient setSpecifiedContentType:temp.copy];

8. 设置自定义请求参数

调用 setRequestParameter 设置自定义参数，以便您对上传日志进行排查。代码示例如下所示：

[self.uploader setRequestParameter:@[BDFileUploadCustomedParameter: "appid=123&did=123456&uid=12345&Region=xxx"]]

参数说明

9. 设置 HttpDns 重试

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

// 获取上传实例
BDImageXUploaderClient *imageXUploadClient = [[BDImageXUploaderClient alloc] initWithFilePaths:<#arrary#>];

// 对 imageXUploadClient 实例开启 httpdns 重试功能，取值请均指定为 YES
[imageXUploadClient setEnableExternDNS:YES];
[imageXUploadClient setEnableHttpDnsRetry:YES];

// 设置文件的上传重试次数，取值请务必设置为大于或等于 2，默认值为 3。
[imageXUploadClient setUploadConfig:@{
    BDFileUploadFileRetryCount:@(2),
}];

10. 设置云控

云控指通过控制台参数的配置，对客户端 SDK 进行配置下发，适用于业务需要灵活修改配置参数的场景。控制台配置操作指南参看 SDK 配置下发。
云控功能默认不开启，如果需要开启则需在 SDK 初始化中添加如下代码：

// 开启云控配置下发功能
configuration.shouldUseCloudControl = YES;
// 如果需要指定deviceID进行配置下发，则可以通过一下代码配置deviceID
configuration.logConfiguration = [[TTSDKLogConfiguration alloc] init];
configuration.logConfiguration.deviceID = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
// TTSDK 初始化
[TTSDKManager startWithConfiguration:configuration];

11. 其他配置

您可在开始上传前调用 setUploadConfig 方法进行配置如下可选能力。

示例代码如下所示。

.......
    [imageXUploadClient setUploadConfig:@{
        BDFileUploadSliceThreshold:@(1000000)
        BDFileUploadSliceSize:@(512*1024),
        BDFileUploadSocketNum:@(4),
        BDFileUploadTcpOpenTimeOutMilliSec:@(5000),
        BDFileUploadMaxFailTimes:@(5),
        BDFileUploadRWTimeout:@(40),
        BDFileUploadSliceRetryCount:@(5),
        BDFileUploadFileRetryCount:@(5),
        BDFileUploadTranTimeOutUnit:@(30),
        BDFileUploadHttpsEnable:@(BDUploadHttpsOpen),
        BDFileUploadMaxConcurrentFileNum:@(3)
    }];
.......