对象存储

  • 对象存储 > SDK 下载 > Objective-C SDK

    Objective-C SDK

    最近更新时间:2020-09-11 17:58:46

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

    安装

    使用 Cocoapods 进行安装,命令如下:

    pod "Qiniu", "~> 8.0"
    

    运行环境

    Qiniu SDK 版本 最低 iOS 版本 最低 OS X 版本 Notes
    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.

    安全机制

    该 SDK 未包含凭证生成相关的功能。开发者对安全性的控制应遵循安全机制中建议的做法,即客户端应向业务服务器每隔一段时间请求上传凭证,而不是直接在客户端使用 AccessKey / SecretKey 生成对应的凭证。在客户端使用 SecretKey 会导致严重的安全隐患。

    开发者可以在生成上传凭证前通过配置上传策略来控制上传的后续动作,例如在上传完成后通过回调机制通知业务服务器。该工作在业务服务器端进行,因此非本 SDK 的功能范畴。

    存储的服务端SDK提供了上传凭证的生成功能,请参考各个服务端语言的SDK文档。

    上传文件

    SDK 内置两种上传方式:表单上传和分片上传,并根据具体情况,内部做了自动切换。表单上传使用一个 HTTP POST 请求完成文件的上传,因此比较适合较小的文件和较好的网络环境。相比而言,分片上传更能适应不稳定的网络环境,也比较适合上传比较大的文件(例如数百 MB 或更大)。

    若需深入了解上传方式之间的区别,请参阅上传类型中表单上传分片上传接口说明。

    #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 错误。

    简单上传

    //国内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

    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.useConcurrentResumeUpload = YES; // 默认为NO
        builder.concurrentTaskCount = 3; // 默认并行线程数为3
    }];
    QNUploadManager *upManager = [[QNUploadManager alloc] initWithConfiguration:config];
    

    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 (c) 2014 qiniu.com

    基于 MIT 协议发布:

    以上内容是否对您有帮助?
  • Qvm free helper
    Close