重要提示
如果您是新接入COS SDK的用户，请勿使用该版本的SDK。
对于新接入COS SDK的用户，我们推荐使用基于XML API封装的SDK。如果因为某些原因仍需要使用基于JSON API封装的SDK，请使用重构的V4 SDK。
开发准备
SDK 获取
对象存储服务的iOS SDK下载地址：iOS SDK
更多示例可参考Demo：iOS Demo （本版本SDK基于JSON API封装组成）
开发准备
- iOS 8.0+；
- 手机必须有网络（GPRS、3G或WiFi网络等）；
- 从控制台获取APP ID、SecretID、SecretKey。
SDK 配置
SDK 导入
使用Cocoapods导入
在Podfile文件中使用：
pod "QCloudCOSV4"
使用静态库导入
git clone https://github.com/tencentyun/COS_iOS_SDK.git
将目录coslib下面的文件拖入到工程中即可：
将目录coslib下面的文件拖入到工程拖入工程目录，Xcode会自动将其加入链接库列表中。
并添加以下依赖库：
- CoreTelephony
- Foundation
- SystemConfiguration
工程配置
在 Build Settings 中设置 Other Linker Flags，加入参数 -ObjC。
在工程info.plist文件中添加App Transport Security Settings类型，然后在App Transport Security Settings下添加Allow Arbitrary Loads类型为Boolean，值设为YES。
如果想要在程序中使用HTTPS协议，请做如下设置：
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:@"sh";//@“sh”bucket所在机房
[client openHttpsRequest:YES];初始化
引入上传SDK的头文件 COSClient.h，使用目录操作时，需要先实例化COSClient对象。
方法原型
- (instancetype)initWithAppId:(NSString*)appId withRegion:(NSString *)region;参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| appId | NSString* | 是 | 项目ID，即APP ID。 |
| region | NSString* | 是 | bucket在创建时指定机房区域，例如华东园区：“sh”，华南园区："gz"，华北园区："tj"。 |
示例
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:@“sh”];快速入门
在这里演示了上传和下载的基本流程，更多细节可以参考demo；在进行这一步之前必须在腾讯云控制台上申请COS业务的appid；
步骤 - 1 初始化COSClient
示例
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];步骤 - 2 上传文件
在此假设您已经申请了自己的业务bucket。SDK中的所有任务对应了相应的task，只需将相应的task参数传递给client，即可完成相应的动作；
示例
COSObjectPutTask *task = [COSObjectPutTask new];
task.filePath = path;
task.fileName = fileName;
task.bucket = bucket;
task.attrs = @"customAttribute";
task.directory = dir;
task.insertOnly = YES;
task.sign = _sign;
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
client.progressHandler = ^(NSInteger bytesWritten,NSInteger totalBytesWritten,NSInteger totalBytesExpectedToWrite){
//progress
};
[client putObject:task];步骤 - 3 下载文件
示例
COSObjectGetTask *cm = [[COSObjectGetTask alloc] initWithUrl:imgUrl.text];
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
//
};
client.downloadProgressHandler = ^(int64_t receiveLength,int64_t contentLength){
};
[client getObjectRequest:cm];生成签名
签名类型：
| 类型 | 含义 |
|---|---|
| 多次有效 | 有效时间内多次始终有效 |
| 单次有效 | 与资源URL绑定，一次有效 |
签名获取：
移动端 SDK 中用到的签名，推荐使用服务器端 SDK，并由移动端向业务服务器请求。
目录操作
目录创建
方法原型
通过此接口在指定的 bucket 下创建目录，具体步骤如下：
- 实例化 COSCreateDirCommand 对象；
- 调用 COSClient 的 createDirRequest 方法，将 COSCreateDirCommand 对象传入。
- 通过 COSCreatDirTaskRsp 的对象返回结果
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| dir | NSString* | 是 | 目录路径（相对于bucket的路径） |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
| attrs | NSString* | 否 | 用户自定义属性 |
返回结果说明
通过 COSCreatDirTaskRsp 的对象返回结果
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码 |
| descMsg | NSString* | 任务描述信息 |
示例
COSCreateDirCommand *cm = [COSCreateDirCommand new];
cm.directory = dir;
cm.bucket = bucket;
cm.sign = _sign;
cm.attrs = @"dirTest";
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{
//fail
}
};
[client createDir:cm];目录属性更新
方法原型
通过调用此接口更新目录的自定义属性，具体步骤如下：
- 实例化 COSUpdateDirCommand 对象；
- 调用 COSClient 的 updateDirRequest 方法，将 COSUpdateDirCommand 对象传入；
- 通过 COSUpdateDirTaskRsp 对象返回结果
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| dir | NSString* | 是 | 目录路径（相对于bucket的路径） |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
| attrs | NSString* | 否 | 用户自定义属性 |
返回结果说明
通过 COSUpdateDirTaskRsp 的对象返回结果
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码 |
| descMsg | NSString* | 任务描述信息 |
示例
COSUpdateDirCommand *cm = [COSUpdateDirCommand new];
cm.directory = dir;
cm.bucket = bucket;
cm.sign = _sign;//本业务使用一次性签名
cm.attrs = @"dirTest";
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
[client updateDir:cm];目录属性查询
方法原型
通过调用此接口查询目录的详细属性，具体步骤如下：
- 实例化 COSDirmMetaCommand 对象；
- 调用 COSClient 的 getDirMetaData 方法，将 COSDirmMetaCommand 对象传入；
- 通过 COSDirMetaTaskRsp 的对象返回结果信息；
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| dir | NSString* | 是 | 目录路径（相对于bucket的路径） |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
返回结果说明
通过COSDirmetaCommand对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码 |
| descMsg | NSString* | 任务描述信息 |
| data | NSDictionary * | 任务描述信息 |
示例
COSDirmMetaCommand *cm = [COSDirmMetaCommand new];
cm.directory = dir;
cm.bucket = bucket;
cm.sign = sign;
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
[client getDirMetaData:cm];目录删除
方法原型
调用此接口，进行指定bucket下目录的删除，如果目录中存在有效文件或目录，将不能删除。具体步骤如下：
- 实例化COSDeleteDirCommand对象；
- 调用COSClient的deleteDirRequest命令，传入COSDeleteDirCommand对象；
- 通过COSdeleteDirTaskRsp的对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| dir | NSString* | 是 | 目录路径（相对于bucket的路径） |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
返回结果说明
通过COSdeleteDirTaskRsp的对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码 |
| descMsg | NSString* | 任务描述信息 |
示例
COSDeleteDirCommand *cm = [COSDeleteDirCommand new];
cm.directory = dir;
cm.bucket = bucket;
cm.sign = _oneSign;//删除使用一次性签名
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess;
}else{}
};
[client deleteDir:cm];目录列表
方法原形
调用此接口可以列出 bucket 中，指定目录下的文件、目录信息，具体步骤如下：
- 实例化 COSListDirCommand 对象；
- 调用 COSClient 对象的 listDirRequest 方法，将 COSListDirCommand 对象传入;
- 通过COSDirListTaskRsp 的对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| path | NSString* | 是 | 目录路径（相对于bucket的路径） |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
| num | NSUInteger | 是 | 一次拉取数目设定 |
| pageContext | NSString* | 是 | 透传字段，查看第一页，则传空字符串。若需要翻页，需要将前一页返回值中的 context 透传到参数中 |
| prefix | NSString* | 是 | 前缀查询 |
返回结果说明
通过 TXYListDirCommandRsp 的对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| context | NSString* | 目录个数 |
| listover | NSString* | 文件个数 |
| infos | NSArray * | 文件目录属性列表 |
| retCode | int | 任务描述代码 |
| descMsg | NSString* | 任务描述信息 |
示例
COSListDirCommand *cm = [COSListDirCommand new]；
cm.directory = dir;
cm.bucket = bucket;
cm.sign = _sign;
cm.number = 100;
cm.pageContext = @"";
cm.prefix = @"xx";
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
[client listDir:cm];文件操作
初始化
方法原型
与目录操作相同，在进行文件操作之前，需引入上传 SDK 的头文件 COSClient .h，实例化 COSClient 对象。
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| appId | NSString* | 是 | 项目ID，即APP ID。 |
| region | NSString* | 是 | bucket 被创建时的机房区域，如上海：“sh”，广州：“gz” |
示例
- (instancetype)initWithAppId:(NSString*)appId withRegion:(NSString *)region;文件上传
方法原型
调用此接口者可进行本地文件上传操作，具体步骤如下：
- 实例化 COSObjectPutTask ；
- 调用 COSClient 对象的 putObject 方法，将 COSObjectPutTask 对象传入；
- 通过 COSObjectUploadTaskRsp 对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filePath | NSString* | 是 | 文件路径 |
| sign | NSString* | 是 | 签名 |
| bucket | NSString* | 是 | 目标 Bucket 名称 |
| fileName | NSString* | 是 | 目标文件在上传到 cos 后显示的名称 |
| attrs | NSString* | 否 | 文件自定义属性 |
| directory | NSString* | 是 | 文件上传目录，相对路径，例如：“/path” |
| insertOnly | BOOL | 是 | 上传文件的动作是插入覆盖，例如“YES”，文件不会覆盖先前的上传文件 |
返回结果说明
通过 COSObjectUploadTaskRsp 对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
| sourceURL | NSString* | 成功后，后台返回文件的 CDN URL |
| sourceURL | NSString* | 成功后，后台返回文件的源站 URL |
示例
COSObjectPutTask *task = [COSObjectPutTask new];
task.filePath = path;
task.fileName = fileName;
task.bucket = bucket;
task.attrs = @"customAttribute";
task.directory = dir;
task.insertOnly = YES;
task.sign = _sign;
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
client.progressHandler = ^(NSInteger bytesWritten,NSInteger totalBytesWritten,NSInteger totalBytesExpectedToWrite){
//progress
};
[client putObject:task];文件属性更新
方法原型
调用此接口更新文件的自定义属性，具体步骤如下：
- 实例化 COSObjectUpdateCommand 对象；
- 调用 COSClient 的 updateObject 命令，传入 COSObjectUpdateCommand 对象；
- 通过 COSObjectUpdateTaskRsp 对象获取返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| fileName | NSString* | 是 | |
| bucket | NSString* | 是 | 目录所属 bucket 名称 |
| sign | NSString* | 是 | 签名 |
| attrs | NSString* | 否 | 用户自定义属性 |
返回结果说明
通过 TXYUpdateCommandRsp 对象获取返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
示例
COSObjectUpdateCommand *cm = [COSObjectUpdateCommand new]
cm.fileName = file;
cm.bucket = bucket;
cm.sign = _oneSign;//单次签名
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{
};
[client updateObject:cm];文件属性查询
方法原型
通过此接口可查询文件的属性信息，具体步骤如下：
- 实例化 COSObjectMetaCommand 对象；
- 调用 COSClient 的 getObjectInfo 命令，传入 COSObjectMetaCommand 对象；
- 通过COSObjectMetaTaskRsp 类返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filename | NSString* | 是 | |
| bucket | NSString* | 是 | 文件所属 bucket 名称 |
| directory | NSString* | 是 | 目录路径（相对于bucket的路径） |
| sign | NSString* | 是 | 签名 |
返回结果说明
通过TXYStatCommandRsp类返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
| data | NSDictionary * | 成功时，返回文件基本信息 |
示例
COSObjectMetaCommand *cm = [COSObjectMetaCommand new] ;
cm.fileName = file;
cm.bucket = bucket;
cm.directory = dir;
cm.sign = _oneSign;//单次签名
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
[client getObjectMetaData:cm];
文件删除
方法原型
调用此接口进行文件的删除操作，具体步骤如下：
- 实例化 COSObjectDeleteCommand 对象；
- 调用 COSClient 的 deleteObject 命令，传入 COSObjectDeleteCommand 对象。
- 通过COSObjectDeleteTaskRsp的对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filename | NSString* | 是 | |
| bucket | NSString* | 是 | 文件所属 Bucket 名称 |
| directory | NSString* | 是 | 目录路径（相对于bucket的路径） |
| sign | NSString* | 是 | 签名 |
| objectType | TXYObjectType | 是 | 业务类型，文件删除时设置为：TXYObjectFile |
返回结果说明
通过COSObjectDeleteTaskRsp的对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
示例
COSObjectDeleteCommand *cm = [COSObjectDeleteCommand new]；
cm.fileName = file;
cm.bucket = bucket;
cm.directory = dir;
cm.sign = _oneSign;//单次签名
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];;
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{ }
};
[client deleteObject:cm];文件下载
方法原型
调用此接口进行文件的下载操作，具体步骤如下：
- 实例化 COSObjectGetTask 对象；
- 调用 COSClient 的 getObjectRequest 命令，传入 COSObjectGetTask 对象。
- 通过COSGetObjectTaskRsp 的对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filePath | NSString* | 是 | 文件下载地址 |
返回结果说明
通过COSGetObjectTaskRsp 的对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
| object | NSMutableData * | 下载文件 |
示例
COSObjectGetTask *cm = [[COSObjectGetTask alloc] initWithUrl:imgUrl.text];
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
//
};
client.downloadProgressHandler = ^(int64_t receiveLength,int64_t contentLength){
};
[client getObject:cm];
文件分片上传
方法原型
调用此接口进行文件的下载操作，具体步骤如下：
- 实例化 COSObjectPutTask 对象；
- 调用 COSClient 的 putObject 命令，传入 COSObjectPutTask 对象。
- 通过COSObjectUploadTaskRsp 的对象返回结果信息
- 当multipartUpload 参数设置为YES 的时候上传文件的方式为分片上传，该参数默认为NO；
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filePath | NSString* | 是 | 文件路径 |
| multipartUpload | BOOL | 否 | 文件上传是否使用分片上传 |
| sign | NSString* | 是 | 签名 |
| bucket | NSString* | 是 | 目标 Bucket 名称 |
| fileName | NSString* | 是 | 目标文件在上传到 cos 后显示的名称 |
| attrs | NSString* | 否 | 文件自定义属性 |
| directory | NSString* | 是 | 文件上传目录，相对路径，例如：“/path” |
| insertOnly | BOOL | 是 | 上传文件的动作是插入覆盖，例如“YES”，文件不会覆盖先前的上传文件 |
返回结果说明
通过COSObjectUploadTaskRsp 的对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
示例
COSObjectPutTask *task = [[COSObjectPutTask alloc] init];
task.multipartUpload = YES;//分片上传设置参数
task.filePath = path;
task.fileName = fileName;
task.bucket = bucket;
task.attrs = @"customAttribute";
task.directory = dir;
task.insertOnly = YES;
task.sign = _sign;
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region]; client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (rsp.retCode == 0) {
//sucess
}else{ }
};
client.progressHandler = ^(NSInteger bytesWritten,NSInteger totalBytesWritten,NSInteger totalBytesExpectedToWrite){
//进度
};
[client putObject:task];文件断点续传
方法原型
调用此接口进行文件的下载操作，具体步骤如下：
- 实例化 COSObjectPutTask ；
- 调用 COSClient 对象的 putObject 方法，将 之前上传过的COSObjectPutTask 对象传入；
- 通过 COSObjectUploadTaskRsp 对象返回结果信息
参数说明
| 参数名称 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| filePath | NSString* | 是 | 文件路径 |
| sign | NSString* | 是 | 签名 |
| bucket | NSString* | 是 | 目标 Bucket 名称 |
| fileName | NSString* | 是 | 目标文件在上传到 cos 后显示的名称 |
| attrs | NSString* | 否 | 文件自定义属性 |
| directory | NSString* | 是 | 文件上传目录，相对路径，例如：“/path” |
| insertOnly | BOOL | 是 | 上传文件的动作是插入覆盖，例如“YES”，文件不会覆盖先前的上传文件 |
返回结果说明
通过 COSObjectUploadTaskRsp 对象返回结果信息
| 属性名称 | 类型 | 说明 |
|---|---|---|
| retCode | int | 任务描述代码，当retCode >= 0时表示成功，为负数则表示失败 |
| descMsg | NSString* | 任务描述信息 |
| sourceURL | NSString* | 成功后，后台返回文件的 CDN URL |
| sourceURL | NSString* | 成功后，后台返回文件的源站 URL |
示例
COSObjectPutTask *task = [COSObjectPutTask new];
task.filePath = path;
task.fileName = fileName;
task.bucket = bucket;
task.attrs = @"customAttribute";
task.directory = dir;
task.insertOnly = YES;
task.sign = _sign;
COSClient *client= [[COSClient alloc] initWithAppId:appId withRegion:[Congfig instance].region];
client.completionHandler = ^(COSTaskRsp *resp, NSDictionary *context){
if (resp.retCode == 0) {
//sucess
}else{}
};
client.progressHandler = ^(NSInteger bytesWritten,NSInteger totalBytesWritten,NSInteger totalBytesExpectedToWrite){
//progress
};
[client putObject:task];