对象存储

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

    Objective-C SDK

    最近更新时间: 2023-12-15 10:39:13

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

    安装

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

    pod "Qiniu", "~> 8.7.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.7.1")
        ],
        // ...
    )
    
    库引入方式:
    import QiniuSDK
    

    运行环境

    Qiniu SDK 版本 最低 iOS 版本 最低 OS X 版本 Notes
    8.7.x iOS 9 OS X 10.15 Xcode 最低版本 11.
    8.6.x iOS 9 OS X 10.15 Xcode 最低版本 11.
    8.5.x iOS 7 OS X 10.15 Xcode 最低版本 11.
    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 上传,默认使用 QNAutoZone,会根据 Bucket 自动查找相应的区域,推荐使用此方式。
    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.useHttps = YES;
    }];
    
    // 如果想使用固定区域,可使用如下方法,强烈推荐使用 QNAutoZone
    // 具体区域 ID 参考:https://developer.qiniu.com/kodo/1671/region-endpoint-fq
    //华东
    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.zone = [QNFixedZone createWithRegionId:@"z0"];
    }];
    
    //华北
    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.zone = [QNFixedZone createWithRegionId:@"z1"];
    }];
    
    //华南
    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.zone = [QNFixedZone createWithRegionId:@"z2"];
    }];
    
    //北美
    QNConfiguration *config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.zone = [QNFixedZone createWithRegionId:@"na0"];
    }];
    
    // 亚太
    QNConfiguration * config = [QNConfiguration build:^(QNConfigurationBuilder *builder) {
        builder.zone = [QNFixedZone createWithRegionId:@"as0"];
    }];
    
    // 重用 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。具体操作请查阅这里

    相关资源

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

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

    贡献代码

    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 协议发布:

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