以下为您介绍 iOS 上传 SDK 的进阶能力。
在文件上传完成后,文件在云端的存储路径形式如下所示:
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 | 文件后缀 | 可选。 |
注意
您可以通过开启重名覆盖上传,使新上传文件在上传路径及文件名重复时覆盖同名旧文件。若不开启,则新文件上传失败。具体使用步骤如下所示:
参考配置重名覆盖上传在 veImageX 控制台打开重名覆盖上传的功能开关。
在组件内开启覆盖上传,代码示例如下所示:
[self.imageXUploadClient setEnableOverwrite:<#BOOL#>];
说明
您可参考最佳实践-全链路数据加解密 进行上传文件加解密全流程操作。
您可通过在 SDK 开启加密上传并使用 AES Key
(自定义或 SDK 生成)加密原始上传文件。使用非对称公钥 RSA Public Key
加密 AES Key
,AES 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 *#>, }];
如果您无需在 veImageX 控制台资源管理查看资源列表,建议您跳过资源上传成功后的媒资上报阶段,以提升上传速度,减少上传耗时。
说明
由于跳过上报阶段后,控制台不再显示上传成功的资源文件,建议您调用 GetImageUploadFiles 接口查看服务下上传文件。
// 设置上传完成后是否写入媒资信息 // 取值如下:1 写入,0 不写入。 // 默认值为 1。 [imageXUploadClient setUploadConfig:@{ // 这里设置为 0,上传成功后会跳过上报阶段 BDFileUploadEnableCommitUpload:@(0), }];
如果您无需在上报阶段使 SDK 返回图片 Meta 信息,建议您跳过图片 Meta 信息上报,以提升上传速度。
// 设置是否返回图片 Meta 信息。 // 取值如下:1 跳过,不返回 meta 信息;0 不跳过,返回 meta 信息。 // 默认值为 0。 [imageXUploadClient setUploadConfig:@{ // 这里设置为 1,上传成功后不会返回 meta 信息 BDFileUploadSkipMeta:@(1), }];
说明
您可参考最佳实践-LivePhoto 上传加载全链路 完成上传加载全链路操作。
支持向 veImageX 服务端上传 LivePhoto 图片,上传的图片可以通过 BDWebImage 进行加载并以苹果官方 LivePhoto 的效果渲染显示。SDK 提供了一个工具类BDImageXLivePhotoUtil
用于在上传 LivePhoto 前先进行打包处理或制作 ,由该工具类打包后,再按照上传流程完成上传。具体流程如下所示:
创建了 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));
初始化用于 LivePhoto 上传的实例
设置上传其他配置,例如加密上传/覆盖上传等。
开始上传。
具体代码示例如下所示。
// 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]; }]; } }];
您可自定义上传文件的 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];
调用 setRequestParameter
设置自定义参数,以便您对上传日志进行排查。代码示例如下所示:
[self.uploader setRequestParameter:@[BDFileUploadCustomedParameter: "appid=123&did=123456&uid=12345&Region=xxx"]]
参数说明
参数名 | 类型 | 说明 |
---|---|---|
BDFileUploadFileType | NSString | 设置上传文件类型,如 image,表示上传图片。 |
BDFileUploadTraceId | NSString | 设置上传跟踪标识,可用于将该次上传操作与业务行为进行关联。 |
BDFileUploadCustomedParameter | NSString | 设置自定义请求参数,如 appid(应用 ID)、did(设备唯一标识)、uid(用户唯一标识) 和 region (地域)等。 |
您可在开始上传前调用 setUploadConfig
方法进行配置如下可选能力。
字段名 | 类型 | 是否必需 | 说明 |
---|---|---|---|
BDFileUploadSliceThreshold | NSNumber(NSIntger) | 否 | 设置分片上传的阈值。若单个文件大小大于阈值则执行分片上传,否则走直传,单位为 byte,默认值为 1 G。 |
BDFileUploadSliceSize | NSNumber(NSInteger) | 否 | 设置分片大小,单位为 byte,默认值为 512KB。 |
BDFileUploadSocketNum | NSNumber(NSInteger) | 否 | 分片上传时的并发连接数。 |
BDFileUploadTcpOpenTimeOutMilliSec | NSNumber(NSInteger) | 否 | 单次 tcp 建连超时,单位为 ms,默认值为 5000ms。 |
BDFileUploadMaxFailTimes | NSNumber(NSInteger) | 否 | 建立连接超时,单位为 s。 |
BDFileUploadRWTimeout | NSNumber(NSInteger) | 否 | 单个分片传输超时时间,单位为 s,默认值为 40s。 |
BDFileUploadSliceRetryCount | NSNumber(NSInteger) | 否 | 单个分片的上传重试次数。 |
BDFileUploadFileRetryCount | NSNumber(NSInteger) | 否 | 文件级别的上传重试次数。 |
BDFileUploadTranTimeOutUnit | NSNumber(NSInteger) | 否 | 系统 socket 单次读写超时,单位为 s。 |
BDFileUploadHttpsEnable | NSNumber(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) }]; .......