Objective-C SDK 为客户端 SDK，没有包含 token 生成实现，为了安全，token 都建议通过网络从服务端获取 具体生成代码可以参考七牛服务端官方 SDK 。支持 Mac 和 iOS，会根据文件大小自动选择表单上传还是断点续上传。

• Objective-C SDK 下载地址
• Objective-C SDK 源码地址
• Objective-C SDK 单元测试

安装

使用 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

运行环境

注意

• 从 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 参考

• 存储 API 参考
• 官方数据处理 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。具体操作请查阅这里。

相关资源

如果您有任何关于我们文档或产品的建议和想法，欢迎您通过以下方式与我们互动讨论：

• 技术论坛 - 在这里您可以和其他开发者愉快的讨论如何更好的使用七牛云服务
• 提交工单 - 如果您的问题不适合在论坛讨论或希望及时解决，您也可以提交一个工单，我们的技术支持人员会第一时间回复您
• 博客 - 这里会持续更新发布市场活动和技术分享文章
• 微博
• 常见问题

贡献代码

1. Fork

2. 创建您的特性分支 git checkout -b my-new-feature

3. 提交您的改动 git commit -am ‘Added some feature’

4. 将您的修改记录提交到远程 git 仓库 git push origin my-new-feature

5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request

许可证

Copyright © 2020 qiniu.com

基于 MIT 协议发布:

• www.opensource.org/licenses/MIT