快速入门

最近更新时间:2019-04-23 16:15:23

下载与安装

相关资源

  • 对象存储服务的 iOS SDK 地址:XML iOS SDK
  • 若您需要下载打包好的 Framework 格式的 SDK,可以从 realease 中选择需要的版本进行下载。
  • 更多示例可参考 Demo: XML iOS SDK Demo
  • COS XML 版本的更新日志请参考:XML iOS SDK ChangeLog

环境依赖

  • SDK 支持 iOS 8.0及以上版本的系统。
  • 手机必须要有网络(GPRS、3G 或 Wi-Fi 网络等)。
  • COS V5 控制台 获取 APPID、SecretId、SecretKey。

说明:

关于文章中出现的 SecretID、SecretKey、Bucket 等名称的含义和获取方式请参考:COS 术语信息

安装 SDK

SDK 导入

您可以通过 cocoapods 或下载打包好的动态库的方式来集成 SDK。在这里我们推荐您使用 cocoapods 的方式来进行导入。

  • 使用 Cocoapods 导入(推荐)
    在 Podfile 文件中使用:

    pod 'QCloudCOSXML'
  • 使用打包好的静态库导入(手动集成方式)
    QCloudCOSXML.framework、QCloudCore.framework 和 libmtasdk.a 拖入到工程中,如下图所示:

    并添加以下依赖库:

    • CoreTelephony
    • Foundation
    • SystemConfiguration
    • libc++.tbd

工程配置

在 Build Settings 中设置 Other Linker Flags,加入以下参数:

-ObjC
-all_load

如下图所示:

注意:

  • 腾讯云对象存储 XML iOS 的 SDK 使用的是 HTTP 协议。为了确保在 iOS 系统上可以运行,您需要开启允许通过 HTTP 传输。
    您可以通过以下两种方式开启允许通过 HTTP 传输:
  • 手动设置方式
    在工程 info.plist 文件中添加 App Transport Security Settings 类型,然后在 App Transport Security Settings 下添加 Allow Arbitrary Loads 类型 Boolean,值设为 YES。
  • 代码设置方式
    您可以在集成 SDK 的 App 的 info.plist 中需要添加如下代码:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
    <key>myqcloud.com</key>
    <dict>
        <key>NSIncludesSubdomains</key>
        <true/>
        <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
        <true/>
    </dict>
</dict>
</dict>
  • SDK 中同时也引入了腾讯移动分析(mta)的功能,若是想关闭该功能,可以通过如下方式进行设置:
  • 导入头文件
    #import <QCloudCore/MTAConfig.h>
  • 在注册完默认的 cosxml 服务之后,添加如下代码:
    [TACMTAConfig getInstance].statEnable = NO;

开始使用

下面为您介绍如何使用 COS iOS SDK 完成一个基础操作,如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。更多细节可以参阅 XML iOS SDK Demo,具体接口如何使用请参照 Demo 中提供的单元测试文件。

注意:

在进行这一步之前必须在 腾讯云控制台 上申请 COS 业务的 APPID。

初始化

在使用 SDK 的功能之前,需要导入一些必要的头文件和进行一些初始化工作。
引入上传 SDK 的头文件:

QCloudCore.h,    
QCloudCOSXML/QCloudCOSXML.h

方法原型

实例化 QCloudServiceConfiguration 对象:

 QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
 configuration.appID = @"APPID"//项目ID;

实例化 QCloudCOSXMLService 对象:

+ (QCloudCOSXMLService*) registerDefaultCOSXMLWithConfiguration:(QCloudServiceConfiguration*)configuration;

实例化 QCloudCOSTransferManagerService 对象:

+ (QCloudCOSTransferMangerService*) registerDefaultCOSTransferMangerWithConfiguration:(QCloudServiceConfiguration*)configuration;
QCloudServiceConfiguration 参数说明
参数名称 说明 类型 必填
appID 项目 ID,即 APPID NSString *
endpoint 配置 endpoint 相关信息 QCloudCOSXMLEndPoint *
QCloudCOSXMLEndPoint 参数说明
参数名称 说明 类型 必填
regionName 服务所属的地域 NSString *
serviceName 域名,默认是:myqcloud.com NSString *
useHTTPS 是否使用 HTTPS 服务,默认是 NO BOOL
suffix 支持自定义 http://bucketname.suffix NSString

初始化示例

下示例中用到的 APPID, SecretId, SecretKey 等可以从 COS v5 控制台 中获取。

注意:

  1. QCloudServiceConfiguration 的 signatureProvider 对象需要实现 QCloudSignatureProvider 协议。
  2. 使用 SDK 操作前,首先要实例化一个默认的云服务配置对象 QCloudServiceConfiguration,其次需要实例化 QCloudCOSXMLService 和 QCloudCOSTransferManagerService 对象。
  3. 如果 QCloudServiceConfiguration 发生改变,可以通过registerCOSTransferMangerWithConfiguration:(QCloudServiceConfiguration*)configuration withKey:(NSString*)key注册一个新的QCloudCOSTransferManagerService,但是默认的 QCloudCOSTransferManagerService 只能有一个。
//AppDelegate.m
//第一步:注册默认的cos服务
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
    configuration.appID = @"APPID";
    configuration.signatureProvider = self;
    QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];
    endpoint.regionName = @"ap-beijing";//服务地域名称,可用的地域请参考注释
    configuration.endpoint = endpoint;
    [QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
    [QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:configuration];
}

//第二步:实现QCloudSignatureProvider协议
- (void) signatureWithFields:(QCloudSignatureFields*)fileds
                     request:(QCloudBizHTTPRequest*)request
                  urlRequest:(NSURLRequest*)urlRequst
                   compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{
//实现签名的过程,我们推荐在服务器端实现签名的过程,具体请参考接下来的 “生成签名” 这一章。
}

创建存储桶

QCloudPutBucketRequest* request = [QCloudPutBucketRequest new];
request.bucket = @"examplebucket-1250000000"; //additional actions after finishing
[request setFinishBlock:^(id outputObject, NSError* error) {
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSXMLService defaultCOSXML] PutBucket:request];

查询存储桶列表

QCloudGetServiceRequest* request = [[QCloudGetServiceRequest alloc] init];
[request setFinishBlock:^(QCloudListAllMyBucketsResult* result, NSError* error) {
//回调完成的处理
}];
[[QCloudCOSXMLService defaultCOSXML] GetService:request];e("CosServerException: " + serverEx.GetInfo());
}

上传对象

假设您已经申请了自己业务 Bucket。事实上,SDK 所有的请求对应了相应的 Request 类,只要生成相应的请求,设置好相应的属性,然后将请求交给 QCloudCOSTransferMangerService 对象,就可以完成相应的动作。其中,request 的 body 部分传入需要上传的对象在本地的 URL(NSURL* 类型)。

上传对象的接口需要用到签名来进行身份认证,发出的请求会自动向初始化时指定的遵循 QCloudSignatureProvider 协议的对象去请求签名。签名如何生成可以参考以下的 生成签名 部分。

注意:

URL 所对应的对象在上传过程中是不能进行变更的,否则会导致出错。

示例

QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
NSURL* url = [NSURL fileURLWithPath:@"filePathString"] /*对象的URL*/;
put.object = @"picture.jpg";
put.bucket = @"examplebucket-1250000000";
put.body =  url;
[put setSendProcessBlock:^(int64_t bytesSent, int64_t totalBytesSent, int64_t totalBytesExpectedToSend) {
    NSLog(@"upload %lld totalSend %lld aim %lld", bytesSent, totalBytesSent, totalBytesExpectedToSend);
}];
[put setFinishBlock:^(id outputObject, NSError* error) {
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

QCloudCOSXMLUploadObjectRequest 参数说明

参数名称 说明 类型 必填
Object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参阅 对象概述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
body 需要上传的文件的路径。填入NSURL * 类型变量 BodyType
storageClass 对象的存储级别 QCloudCOSStorageClass
cacheControl RFC 2616 中定义的缓存策略 NSString *
contentDisposition RFC 2616 中定义的文件名称 NSString *
expect 当使用 expect=@"100-Continue" 时,在收到服务端确认后才会发送请求内容 NSString *
expires RFC 2616 中定义的过期时间 NSString *
initMultipleUploadFinishBlock 如果该 request 产生了分片上传的请求,那么在分片上传初始化完成后,会通过这个 block 来回调,可以在该回调 block 中获取分片完成后的 bucket,key,uploadID,以及用于后续上传失败后恢复上传的 ResumeData block
accessControlList 定义 Object 的 ACL 属性。有效值:private,public-read;默认值:private NSString *
grantRead 赋予被授权者读的权限,格式:id="[OwnerUin]" NSString *
grantWrite 授予被授权者写的权限,格式同上 NSString *
grantFullControl 授予被授权者读写权限,格式同上 NSString *

查询对象列表

QCloudGetBucketRequest* request = [QCloudGetBucketRequest new];
request.bucket = @"examplebucket-1250000000";
request.maxKeys = 1000;
[request setFinishBlock:^(QCloudListBucketResult * result, NSError*   error) {
//additional actions after finishing
}];
[[QCloudCOSXMLService defaultCOSXML] GetBucket:request];

下载对象

QCloudGetObjectRequest* request = [QCloudGetObjectRequest new];
//设置下载的路径 URL,如果设置了,对象将会被下载到指定路径中
request.downloadingURL = [NSURL URLWithString:QCloudTempFilePathWithExtension(@"downding")];
request.object = @"picture";
request.bucket = @"examplebucket-1250000000";
[request setFinishBlock:^(id outputObject, NSError \*error) {
//additional actions after finishing
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[request setDownProcessBlock:^(int64_t bytesDownload, int64_t totalBytesDownload, int64_t totalBytesExpectedToDownload) {
 //下载过程中的进度
}];
[[QCloudCOSXMLService defaultCOSXML] GetObject:request];

删除对象

QCloudDeleteObjectRequest* deleteObjectRequest = [QCloudDeleteObjectRequest new];
deleteObjectRequest.bucket = @"examplebucket-1250000000";
deleteObjectRequest.object = @"text.txt";
__block NSError* resultError;
[deleteObjectRequest setFinishBlock:^(id outputObject, NSError *error) {
    resultError = error;
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSXMLService defaultCOSXML] DeleteObject:deleteObjectRequest];

生成签名

SDK 中的请求需要用到签名,以确认访问的用户的身份,也保障了访问的安全性。当签名不正确时,大部分 COS 的服务将无法访问并且返回403错误。在 SDK 中可以生成签名,每个请求会向 QCloudServiceConfiguration 对象中的signatureProvider 对象来请求生成签名。我们可以将负责生成签名的对象在一开始赋值给 signatureProvider,该生成签名的对象需要遵循 QCloudSignatureProvider 协议,并实现生成签名的方法:

- (void) signatureWithFields:(QCloudSignatureFields* )fileds    
                    request:(QCloudBizHTTPRequest* )request    
                    urlRequest:(NSURLRequest* )urlRequst    
                    compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock

接入 CAM 系统实现临时签名(推荐)

虽然在本地提供了永久的 SecretId 和 SecretKey 来生成签名的接口,但请注意,将永久的 SecretId 和 SecretKey 存储在本地是非常危险的行为,容易造成泄露引起不必要的损失。因此基于安全性的考虑,建议您在服务器端实现签名的过程。

注意:

强烈建议返回服务器时间作为签名的开始时间,用来避免由于用户手机本地时间偏差过大导致的签名不正确。

推荐您在自己的签名服务器内接入腾讯云的 CAM(Cloud Access Manager,访问管理)来实现整个签名流程。

至于如何搭建签名服务器接入 CAM 系统,您可以参考 移动应用直传实践

签名服务器接入 CAM 系统后,当客户端向签名服务器端请求签名时,签名服务器端会向 CAM 系统请求临时证书,然后返回给客户端。
CAM 系统会根据您的永久 SecretId 和 SecretKey 来生成临时的 SecretId,SecretKey 和临时 Token 来生成签名,可以最大限度地提高安全性。终端收到这些临时密钥的信息后,通过它们构建一个 QCloudCredential 对象,然后通过这个 QCloudCredentail 对象生成 QCloudAuthentationCreator,最后通过使用 Creator 来生成包含签名信息的 QCloudSignature 对象。具体的操作可以参考以下示例:

- (void) signatureWithFields:(QCloudSignatureFields*)fileds
                     request:(QCloudBizHTTPRequest*)request
                  urlRequest:(NSURLRequest*)urlRequst
                   compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{
    /*向签名服务器请求临时的 Secret ID,Secret Key,Token*/
    QCloudCredential* credential = [QCloudCredential new];
    credential.secretID = @"AKIDHTVVaVR6e3";
    credential.secretKey = @"PdkhT9e2rZCfy6";
    credential.token = @"从 CAM 系统返回的 Token,为会话 ID"
    /*强烈建议返回服务器时间作为签名的开始时间,用来避免由于用户手机本地时间偏差过大导致的签名不正确 */
    credential.startDate = /*返回的服务器时间*/
    credential.expiretionDate     = /*签名过期时间*/
    QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc] initWithCredential:credential];
    QCloudSignature* signature =  [creator signatureForData:urlRequst];
    continueBlock(signature, nil);
}

在终端使用永久密钥生成签名(不推荐)

注意:

我们不推荐您在终端使用永久密钥生成签名,该方式有泄密数据的风险。

示例代码如下:

- (void) signatureWithFields:(QCloudSignatureFields*)fileds
                     request:(QCloudBizHTTPRequest*)request
                  urlRequest:(NSMutableURLRequest*)urlRequst
                   compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{

    QCloudCredential* credential = [QCloudCredential new];
    credential.secretID = @"AKIDHTVVaVR6e3";
    credential.secretKey = @"PdkhT9e2rZCfy6";
    QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc] initWithCredential:credential];
    QCloudSignature* signature =  [creator signatureForData:urlRequst];
    continueBlock(signature, nil);
}

使用脚手架工具管理异步签名

到这一步时,您已经可以生成签名正常使用 SDK 里面的接口了。但为了方便您实现临时签名,从服务器端获取 tempSecretKey 等临时签名需要的信息,我们提供了脚手架工具可供使用。您可以依照前面的代码来生成签名,也可以通过我们的脚手架工具 QCloudCredentailFenceQueue 来方便地获取临时签名。
QCloudCredentailFenceQueue 提供了栅栏机制,也就是说您使用 QCloudCredentailFenceQueue 获取签名的话,所有需要获取签名的请求会等待签名完成后再执行,免去了自己管理异步过程。
使用 QCloudCredentailFenceQueue,我们需要先生成一个实例。

//AppDelegate.m
//AppDelegate需遵循QCloudCredentailFenceQueueDelegate协议
//
- (BOOL)application:(UIApplication * )application didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {
    // init step
    self.credentialFenceQueue = [QCloudCredentailFenceQueue new];
    self.credentialFenceQueue.delegate = self;
    return YES;
}

然后调用 QCloudCredentailFenceQueue 的类需要遵循 QCloudCredentailFenceQueueDelegate 并实现协议内定义的方法:

- (void) fenceQueue:(QCloudCredentailFenceQueue * )queue requestCreatorWithContinue:(QCloudCredentailFenceQueueContinue)continueBlock

当通过 QCloudCredentailFenceQueue 去获取签名时,所有需要签名的 SDK 里的请求都会等待该协议定义的方法内拿到了签名所需的参数并生成有效的签名后执行。请看以下示例:

//AppDelegate.m
- (void) fenceQueue:(QCloudCredentailFenceQueue * )queue requestCreatorWithContinue:(QCloudCredentailFenceQueueContinue)continueBlock
{
   QCloudCredential* credential = [QCloudCredential new];
   //在这里可以同步过程从服务器获取临时签名需要的secretID,secretKey,expiretionDate和token参数
   credential.secretID = @"AKIDHTVVaVR6e3";
   credential.secretKey = @"PdkhT9e2rZCfy6";
   /*强烈建议返回服务器时间作为签名的开始时间,用来避免由于用户手机本地时间偏差过大导致的签名不正确 */
   credential.startDate =[NSDate dateWithTimeIntervalSince1970:@"返回的服务器时间"]
   credential.experationDate = [NSDate dateWithTimeIntervalSince1970:1504183628];
   credential.token = @"Token";
   QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc] initWithCredential:credential];
   continueBlock(creator, nil);
}
- (void) signatureWithFields:(QCloudSignatureFields*)fileds
                     request:(QCloudBizHTTPRequest*)request
                  urlRequest:(NSMutableURLRequest*)urlRequst
                   compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{
    [self.credentialFenceQueue performAction:^(QCloudAuthentationCreator *creator, NSError *error) {
        if (error) {
            continueBlock(nil, error);
        } else {
            QCloudSignature* signature =  [creator signatureForData:urlRequst];
            continueBlock(signature, nil);    
        }
    }];
}

至此,您就可以通过我们提供的脚手架工具来生成临时签名了,当然您也可以自己去实现具体的签名过程。

精简版 SDK 使用指南

对于部分仅仅使用到上传和下载功能,并且对 SDK 体积要求较高的用户,我们提供了只有上传和下载功能的精简版 SDK,集成进去后的包增量只有完整版的一半。

精简版 SDK 是通过 Cocoapods 的 Subspec 功能实现的,因此目前只支持通过 Cocoapods 集成的方式集成精简版 SDK。需要使用精简版的 SDK 只需要在 Podfile 中加入。

pod 'QCloudCOSXML/Transfer'

注意:

对于 Mobile Line 的用户而言,只有在没有使用 TACStorage 的情况下可以使用精简版的 SDK。与此同时,Cocoapods 的官方源需要在所有源的前面(建议放在 Podfile 的第一行)。其它用户可忽略此说明。

对于精简版的 SDK ,没有 QCloudCOSXML.h 头文件,取而代之的是初始化时需要导入以下的头文件:

#import <QCloudCOSXML/QCloudCOSXMLTransfer.h>
#import <QCloudCore/QCloudCore.h>

精简版 SDK 初始化的过程,上传和下载的接口与完整版 SDK 一致。