Objective-C SDK
Objective-C SDK 为客户端 SDK,没有包含 token 生成实现,为了安全,token 都建议通过网络从服务端获取 具体生成代码可以参考七牛服务端官方 SDK 。支持 Mac 和 iOS,会根据文件大小自动选择表单上传还是断点续上传。
安装
使用 Cocoapods 进行安装,命令如下:
pod "Qiniu", "~> 8.4.1"
通过 Swift Package Manager (Xcode 11+)
App 对接:
File -> Swift Packages -> Add Package Dependency,输入库链接,选择相应版本即可。
库链接: https://github.com/qiniu/objc-sdk
库对接:
let package = Package(
dependencies: [
.package(url: "https://github.com/qiniu/objc-sdk", from: "8.4.1")
],
// ...
)
库引入方式:
import QiniuSDK
运行环境
Qiniu SDK 版本 | 最低 iOS 版本 | 最低 OS X 版本 | Notes |
---|---|---|---|
8.4.x | iOS 7 | OS X 10.15 | Xcode 最低版本 11. |
8.3.x | iOS 7 | OS X 10.15 | Xcode 最低版本 11. |
8.2.x | iOS 7 | OS X 10.15 | Xcode 最低版本 11. |
8.1.x | iOS 7 | OS X 10.15 | Xcode 最低版本 11. |
8.0.x | iOS 7 | OS X 10.15 | Xcode 最低版本 11. |
7.4.x | iOS 7 | OS X 10.9 | Xcode 最低版本 6. |
7.3.x | iOS 7 | OS X 10.9 | Xcode 最低版本 6. |
7.2.x | iOS 7 | OS X 10.9 | Xcode 最低版本 6. |
7.1.x / AFNetworking-3.x | iOS 7 | OS X 10.9 | Xcode 最低版本 6. |
7.0.x / AFNetworking-2.x | iOS 6 | OS X 10.8 | Xcode 最低版本 5. |
7.x / AFNetworking-1.x | iOS 5 | OS X 10.7 | Xcode 最低版本 5. |
6.x | iOS 6 | None | Xcode 最低版本 5. |
注意
- 从 7.4.0 开始增加了 DNS 预解析和缓存策略(每 2 分钟(进程非挂起状态)会自动刷新缓存策略),减少 DNS 解析错误。默认预解析开启,可以通过设置 kQNGlobalConfiguration.isDnsOpen = false 关闭该功能。
- 从 8.3.1 版本开始支持设置缓存有效期,默认 10 分钟,可修改 kQNGlobalConfiguration.dnsCacheMaxTTL 的值,单位为 s。
安全机制
该 SDK 未包含凭证生成相关的功能。开发者对安全性的控制应遵循 安全机制 中建议的做法,即客户端应向业务服务器每隔一段时间请求 上传凭证 ,而不是直接在客户端使用 AccessKey / SecretKey 生成对应的凭证。在客户端使用 SecretKey 会导致严重的安全隐患。
开发者可以在生成上传凭证前通过配置 上传策略 来控制上传的后续动作,例如在上传完成后通过回调机制通知业务服务器。该工作在业务服务器端进行,因此非本 SDK 的功能范畴。
存储的服务端 SDK 提供了上传凭证的生成功能,请参考各个服务端语言的 SDK 文档。
上传
SDK 内置两种上传方式:表单上传和分片上传,并根据具体情况,内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传,因此比较适合较小的文件和较好的网络环境。相比而言,分片上传更能适应不稳定的网络环境,也比较适合上传比较大的文件(例如数百 MB 或更大)。
若需深入了解上传方式之间的区别,请参阅上传类型中 表单上传 、分片上传 v1 版和 分片上传 v2 版 接口说明。
#import <QiniuSDK.h>
...
NSString *token = @"从服务端SDK获取";
QNUploadManager *upManager = [[QNUploadManager alloc] init];
NSData *data = [@"Hello, World!" dataUsingEncoding : NSUTF8StringEncoding];
[upManager putData:data key:@"hello" token:token
complete: ^(QNResponseInfo *info, NSString *key, NSDictionary *resp) {
NSLog(@"%@", info);
NSLog(@"%@", resp);
} option:nil];
...
**注意:**key 及所有需要输入的字符串必须采用 utf8 编码,如果使用非 utf8 编码访问 七牛云存储 将反馈错误。
option
关于 option 参数,一般情况下,开发者可以忽略 put 方法中的 option 参数,即在调用时保持 option 的值为 nil 即可。但对于一些特殊的场景,我们可以给 option 传入一些高级选项以更精确的控制上传行为和获取进度信息。option QNUploadOption 类型包含的变量有:params、mimeType、checkCrc、progressHandler、cancelSignal。
params
用户自定义参数,必须以 x:
开头,这些参数可以作为变量用于 upToken 的 callbackBody、returnBody、asyncOps 参数中,具体信息请参阅自定义变量。
一个简单的例子如下:
QNUploadOption *opt = [[QNUploadOption alloc] initWithMime:@"text/plain" progressHandler:nil params:@{ @"x:foo":@"fooval" } checkCrc:YES cancellationSignal:nil];
[upManager putData:data key:@"hello" token:token
complete: ^(QNResponseInfo *info, NSString *key, NSDictionary *resp) {
NSLog(@"%@", info);
NSLog(@"%@", resp);
} option:opt];
mimeType
为上传文件设置一个自定义的 MIME 类型,如果为空,那么服务端自动检测文件的 MIME 类型。
checkCrc
checkCrc 为 NO 时,服务端不会校验 crc32 值,checkCrc 为 YES 时,服务端会计算上传文件的 crc32 值,然后与用户提供的 crc32 参数值比较确认文件的完整性,如果校验失败会返回 406 错误。
简单上传
//选择最新的分片上传版本
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.resumeUploadVersion = QNResumeUploadVersionV2;
}];
//国内https上传
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.useHttps = YES;
}];
//华东
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.zone = [QNFixedZone zone0];
}];
//华北
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.zone = [QNFixedZone zone1];
}];
//华南
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.zone = [QNFixedZone zone2];
}];
//北美
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.zone = [QNFixedZone zoneNa0];
}];
//海外https上传
QNConfiguration * config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.zone = [QNFixedZone zoneNa0];
builder.useHttps = YES;
}];
//重用uploadManager。一般地,只需要创建一个uploadManager对象
NSString * token = @"从服务端SDK获取";
NSString * key = @"指定存储服务上的文件名,或nil";
NSString * filePath = @"要上传的文件路径";
QNUploadManager *upManager = [[QNUploadManager alloc] initWithConfiguration:config];
[upManager putFile:filePath key:key token:token complete:^(QNResponseInfo *info, NSString *key, NSDictionary *resp) {
if(info.ok)
{
NSLog(@"请求成功");
}
else{
NSLog(@"失败");
//如果失败,这里可以把info信息上报自己的服务器,便于后面分析上传错误原因
}
NSLog(@"info ===== %@", info);
NSLog(@"resp ===== %@", resp);
} option:nil];
注意:
7.1.4版本之后, 可自动判断上传空间,不设置QNConfiguration的zone参数即可:
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.useHttps = YES;
}];
QNUploadManager *upManager = [[QNUploadManager alloc] initWithConfiguration:config];
上传进度
上传进度的 block 为:
typedef void (^QNUpProgressHandler)(NSString *key, float percent);
如果实现了这个 block,并作为 option 参数传入,会及时得到上传进度通知。
取消上传
如果希望中途可以取消上传,需要实现下面的 block,并作为参数传入 option:
typedef BOOL (^QNUpCancellationSignal)(void);
当执行取消操作时,让这个函数返回 YES,这样上传中途即可停止,具体请参考 QNFileRecorderTest.m 测试中的例子。
断点续上传
本 SDK 实现了断点续上传,如果需要保存上传进度,需要您在生成 UploaderManager 实例时传入一个实现保存进度的代理,SDK 自带了将进度保存进文件的方法,您可以自己实现其他保存方式。具体请参考 QNFileRecorderTest.m 测试中的例子。
NSError *error;
QNFileRecorder *file = [QNFileRecorder fileRecorderWithFolder:@"保存目录" error:&error];
//check error
QNUploadManager *upManager = [[QNUploadManager alloc] initWithRecorder:file];
分片上传
SDK 从 v7.3.0 开始支持并行分片上传,上传代码可以参考 QNConcurrentResumeUploadTest.m。
可以选择分片上传版本,推荐 QNResumeUploadVersionV2,表示分片上传 v2 版,默认QNResumeUploadVersionV1,表示分片上传 v1 版,兼容历史情况。
QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
builder.resumeUploadVersion = QNResumeUploadVersionV2; // 选择分片上传版本
builder.useConcurrentResumeUpload = YES; // 开启并发上传,默认为 NO
builder.concurrentTaskCount = 3; // 默认并行线程数为 3
}];
QNUploadManager *upManager = [[QNUploadManager alloc] initWithConfiguration:config];
inputStream 流上传
SDK 从 v8.3.0 开始支持 inputStream 流上传。
NSInputStream *inputStream = nil; // file input stream
NSString *sourceId = @""; // source 作为断点续传的标识,保证每个文件不同
long long size = -1; // input stream 大小,不知道时为 -1,size 对progress 进度有影响
NSString *key = @""; // 存储的key
NSString *token = @""; // 七牛token
[upManager putInputStream:inputStream sourceId:sourceId size:size fileName:key key:key token:token complete:^(QNResponseInfo *info, NSString *k, NSDictionary *resp) {
} option:option];
API 参考
常见问题
- 如果碰到 crc 链接错误,请把 libz.dylib 加入到项目中去。
- 如果碰到 res_9_ninit 链接错误,请把 libresolv.dylib 加入到项目中去。
- 如果需要支持 iOS 5 或者支持 RestKit,请用 AFNetworking 1.x 分支的版本。
- 如果碰到其他编译错误,请参考 Cocoapods 的troubleshooting。
- iOS 9+ 强制使用 https ,需要在 project build info 添加 NSAppTransportSecurity 类型 Dictionary。在 NSAppTransportSecurity下添加 NSAllowsArbitraryLoads 类型 Boolean ,值设为 YES。具体操作请查阅这里。
相关资源
如果您有任何关于我们文档或产品的建议和想法,欢迎您通过以下方式与我们互动讨论:
- 技术论坛 - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
- 提交工单 - 如果您的问题不适合在论坛讨论或希望及时解决,您也可以提交一个工单,我们的技术支持人员会第一时间回复您
- 博客 - 这里会持续更新发布市场活动和技术分享文章
- 微博
- 常见问题
贡献代码
-
Fork
-
创建您的特性分支 git checkout -b my-new-feature
-
提交您的改动 git commit -am ‘Added some feature’
-
将您的修改记录提交到远程 git 仓库 git push origin my-new-feature
-
然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request
许可证
Copyright © 2020 qiniu.com
基于 MIT 协议发布: