You need to enable JavaScript to run this app.
导航
进阶功能
最近更新时间:2024.09.10 11:22:26首次发布时间:2022.10.24 10:59:56

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

1. 设置云端存储 Key

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

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

各参数说明如下表所示:

参数含义描述
BucketName存储桶名称接入方无需手动设置。
FilePrefix文件前缀可选,路径字符串,支持多级路径(如 path/to/foo/bar/)
FileTitle文件标题可选,如果不手动设置,SDK 会自动生成 32 位字符串作为文件名。
FileExtension文件后缀可选。

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

#import <TTSDK/BDFileUploaderHeader.h>

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

} 

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

字段含义说明
tos-cn-xxxx/存储桶名称接入方无需手动设置。
testPrefix/文件前缀可选。
test0文件名可选。若不手动设置,SDK 将自动生成一个 32 位字符串作为文件名。
.jpg文件后缀可选。

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

注意

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

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

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

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

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

3. 设置加密上传

说明

您可参考最佳实践-全链路数据加解密 进行上传文件加解密全流程操作。

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

注意

您需要对AES Key的完整性和正确性负责,因您维护不当导致AES Key用错或丢失,从而导致加密数据无法解密所引起的一切损失和后果均由您自行承担。

[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 控制台资源管理查看资源列表,建议您跳过资源上传成功后的媒资上报阶段,以提升上传速度,减少上传耗时。

说明

由于跳过上报阶段后,控制台不再显示上传成功的资源文件,建议您调用 GetImageUploadFiles 接口查看服务下上传文件。

// 设置上传完成后是否写入媒资信息
// 取值如下:1 写入,0 不写入。
// 默认值为 1。
[imageXUploadClient setUploadConfig:@{
    // 这里设置为 0,上传成功后会跳过上报阶段
    BDFileUploadEnableCommitUpload:@(0),
}];

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

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

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

6. 上传 LivePhoto

说明

您可参考最佳实践-LivePhoto 上传加载全链路 完成上传加载全链路操作。

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

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

创建了 BDImageXLivePhotoUtil 实例 livePhotoUtil,用于打包 LivePhoto。并传递 LivePhoto 对象 livp 和标题 title。若打包错误,调用 completion 回调并传递错误信息;若打包成功,则将打包后的 LivePhoto 拷贝到工作目录下。

/// 打包一个 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));
  
  1. 初始化用于 LivePhoto 上传的实例

  2. 设置上传其他配置,例如加密上传/覆盖上传等。

  3. 开始上传。

具体代码示例如下所示。

// 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];
        }];
        
    }
}];
  

7. 设置文件的 Content-Type

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

说明

若您上传的目标服务已配置服务维度的 Content-Type 白名单限制。那么,此处设置的文件 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"]]

参数说明

参数名类型说明
BDFileUploadFileTypeNSString设置上传文件类型,如 image,表示上传图片。
BDFileUploadTraceIdNSString设置上传跟踪标识,可用于将该次上传操作与业务行为进行关联。
BDFileUploadCustomedParameterNSString设置自定义请求参数,如 appid(应用 ID)、did(设备唯一标识)、uid(用户唯一标识) 和 region (地域)等。

9. 其他配置

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

字段名类型是否必需说明
BDFileUploadSliceThresholdNSNumber(NSIntger)设置分片上传的阈值。若单个文件大小大于阈值则执行分片上传,否则走直传,单位为 byte,默认值为 1 G。
BDFileUploadSliceSizeNSNumber(NSInteger)设置分片大小,单位为 byte,默认值为 512KB。
BDFileUploadSocketNumNSNumber(NSInteger)分片上传时的并发连接数。
BDFileUploadTcpOpenTimeOutMilliSecNSNumber(NSInteger)单次 tcp 建连超时,单位为 ms,默认值为 5000ms。
BDFileUploadMaxFailTimesNSNumber(NSInteger)建立连接超时,单位为 s。
BDFileUploadRWTimeoutNSNumber(NSInteger)单个分片传输超时时间,单位为 s,默认值为 40s。
BDFileUploadSliceRetryCountNSNumber(NSInteger)单个分片的上传重试次数。
BDFileUploadFileRetryCountNSNumber(NSInteger)文件级别的上传重试次数。
BDFileUploadTranTimeOutUnitNSNumber(NSInteger)系统 socket 单次读写超时,单位为 s。
BDFileUploadHttpsEnableNSNumber(BDUploadHttpsOpen)是否开启 https,可以根据上传阶段分步开启。

BDFileUploadMaxConcurrentFileNum

NSNumber(NSInteger)

同时上传多个图片时,并发上传的文件数量,默认值为 1。建议取值不超过待上传的文件数量。

说明

请根据实际情况适当调整并发量,但不建议取值过大,以免导致上传失败率提高。

示例代码如下所示。

.......
    [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)
    }];
.......