对象操作

最近更新时间:2019-04-30 11:47:58

简介

本文档重点提供关于对象的简单操作、分块操作以及其他操作相关的 API 概览以及 SDK 示例代码,并且举例如何使用。

  • 我们假设您已经按照 快速入门 文档中的指引完成了 SDK 下载、安装和初始化的过程。
  • 查询时建议使用 Command+F 搜索到想要查询的接口,然后看我们给出的接口简单说明,复制示例到您的工程中运行。

    说明:

    如果需要了解接口的功能或者参数的意义,建议直接查看代码里的注释,Xcode 支持通过三指轻按、Force-touch 重按或者将鼠标停留在变量上,按 Control+Command+D 的方式查看它的释义。

简单操作

API 操作名 操作描述
GET Bucket(List Object) 获取对象列表 获取存储桶中的对象列表
PUT Object 上传对象 上传一个 Object(文件/对象)至 Bucket
HEAD Object 获取对象元数据 获得 Object 的 Meta 信息
GET Object 获取对象 下载一个 Object(文件/对象)至本地
Options Object 预请求跨域配置 用预请求来确认是否可以发送真正的跨域请求
PUT Object - Copy 设置对象复制 复制文件到目标路径
DELETE Object 删除单个对象 在 Bucket 中删除指定 Object (文件/对象)
DELETE Multiple Object 删除多个对象 在 Bucket 中批量删除 Object (文件/对象)

分块操作

API 操作名 操作描述
List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
Initiate Multipart Upload 初始化分块上传 初始化 Multipart Upload 上传操作
Upload Part 上传分块 分块上传文件
Upload Part - Copy 复制分块 将其他对象复制为一个分块
List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
Complete Multipart Upload 完成分块上传 完成整个文件的分块上传
Abort Multipart Upload 终止分块上传 终止一个分块上传操作并删除已上传的块

其他操作

API 操作名 操作描述
POST Object restore 恢复归档对象 将归档类型的对象取回访问
PUT Object acl 设置对象 ACL 设置 Bucket 中某个 Object (文件/对象)的 ACL
GET Object acl 获取对象 ACL 获取 Object(文件/对象)的 ACL

高级接口(推荐)

该小节中封装了上传和复制的高级接口,用户只需要设置相应的参数,该接口内部会根据文件大小决定是进行简单上传(复制)还是分片上传(复制),使用接口前请确认已完成了 快速入门 中指引的初始化步骤。

上传对象

可以参考快速入门中的 上传对象 环节。

上传对象时的断点续传

对于大于1MB的对象,SDK 都会以分片上传的方式进行上传,即将文件切分成多个1MB大小的分块,然后并行地(最大并行数为4)进行上传。对于每个已经完成上传的分片,后台服务器都会将其保存起来,这是上传时候断点续传的基础。

在分片上传的过程中,初始化分片上传完成、或者是主动取消上传的话,都会产生一个用于恢复上传的 resumeData,可以通过这个 resumetData 重新生成一个上传请求,再继续用这个上传请求上传,即可接着继续上传,并且进度也会相应叠加。可以参照下面获取 ResumeData 的例子:

QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
//设置一些上传的参数
put.initMultipleUploadFinishBlock = ^(QCloudInitiateMultipartUploadResult * multipleUploadInitResult, QCloudCOSXMLUploadObjectResumeData resumeData) {
    //在初始化分片上传完成以后会回调该block,在这里可以获取 resumeData,并且可以通过 resumeData 生成一个分片上传的请求
    QCloudCOSXMLUploadObjectRequest* request = [QCloudCOSXMLUploadObjectRequest requestWithRequestData:resumeData];
};

[[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

//•••在完成了初始化,并且上传没有完成前
NSError* error;
//这里是主动调用取消,并且产生 resumetData 的例子
resumeData = [put cancelByProductingResumeData:&error];
if (resumeData) {
QCloudCOSXMLUploadObjectRequest* request = [QCloudCOSXMLUploadObjectRequest requestWithRequestData:resumeData];
 }
 //生成的用于恢复上传的请求可以直接上传
 [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:request];

注意的是,按照分片上传的运行原理,只有当一个分片上传完了,那么后台服务器才会将该分片记录下来,并且叠加进度。并且以下几种情况无法进行断点续传,而是重新开始一次上传过程:

  • 上传的对象小于1MB,没有进行分片上传。
  • 没有使用 QCloudCOSXMLUploadObjectRequest 类进行上传,而是直接使用简单上传接口。
  • 取消生成 resumeData 时候初始化分片上传还没有完成(完成初始化上传的回调还没有调用)。

下载对象

可以参考快速入门中的 下载对象 章节。

复制对象

说明

先初始化一个 QCloudCOSXMLCopyObjectRequest 对象,然后调用 QCloudCOSTransferMangerService 的 CopyObject 方法即可。注意对于比较大的文件,将会使用分块复制的方式进行复制。这个过程对于用户是没有感知的。

注意:

如果是跨区域复制,这里使用的 transferManager 所在的 region 必须为目标桶所在的 region。

QCloudCOSXMLCopyObjectRequest 参数说明

参数名称 描述 类型 必填
bucket 要创建的存储桶名,您可以在 COS 控制台 上面看到,注意存储桶名只能由数字和小写字母组成,并且长度不能超过40个字符,否则会创建失败 NSString *
sourceBucket 复制的源文件所在 Bucket NSString *
sourceObject 复制的源文件的对象名,key NSString *
sourceAPPID 复制的源文件的 APPID NSString *
sourceRegion 复制的源文件所在的区域 NSString *
metadataDirective 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制;假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced NSString *
storageClass 对象的存储级别,枚举值:STANDARD(QCloudCOSStorageStandard),STANDARD_IA(QCloudCOSStorageStandardIA)。默认值:STANDARD(QCloudCOSStorageStandard) QCloudCOSStorageClass

示例

QCloudCOSXMLCopyObjectRequest* request = [[QCloudCOSXMLCopyObjectRequest alloc] init];
request.bucket = @"examplebucket-1250000000";//目的<BucketName-APPID>,需要是公有读或者在当前账号有权限
request.object = @"text.txt";//目的文件名称
request.sourceBucket = @"examplebucket-1250000000";//文件来源<BucketName-APPID>,需要是公有读或者在当前账号有权限
request.sourceObject = @"text.txt";//源文件名称
request.sourceAPPID = @"appid";//源文件的appid
request.sourceRegion= @"ap-beijing";//来源的地域
[request setFinishBlock:^(QCloudCopyObjectResult* result, NSError* error) {
    //完成回调
   //可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
    if (nil == error) {
      //成功
    }
}];
//注意如果是跨区域复制,这里使用的 transferManager 所在的 region 必须为目标桶所在的 region
[[QCloudCOSTransferMangerService defaultCOSTransferManager] CopyObject:request];

简单操作

获取对象列表

功能说明

获取指定存储桶中所有的对象(Object List)。

方法原型

进行存储桶操作之前,我们需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudGetBucketRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudGetBucketRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 GetBucket 方法发出请求。
  3. 从回调的 finishBlock 中的 QCloudListBucketResult 获取具体内容。

QCloudGetBucketRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
prefix 前缀匹配,用来规定返回的文件前缀地址 NSString *
delimiter 定界符为一个符号,如果有 Prefix,则将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix,然后列出所有 Common Prefix。如果没有 Prefix,则从路径起点开始。可以将其理解为结束的符号,例如如果想要结尾是 A 的结果,那么将delimiter设置为 A 即可。 NSString *
encodingType 规定返回值的编码方式,可选值:url NSString *
marker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 NSString *
maxKeys 单次返回的最大条目数量,默认1000 int

示例

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];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

上传对象

功能说明

上传对象到指定的存储桶中(Put Object),简单上传仅限于小文件(20MB以下)。简单上传支持从内存中上传文件。

注意:

当前访问策略条目限制为1000条,如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承 Bucket 权限。

QCloudPutObjectRequest 参数说明

参数名称 说明 类型 必填
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 * 类型变量。如果文件存放在内存中,则这里可以填入包含文件二进制数据的 NSData * 类型变量 BodyType
storageClass 对象的存储级别,枚举值:STANDARD(QCloudCOSStorageStandard),STANDARD_IA(QCloudCOSStorageStandardIA),ARCHIVE(QCloudCOSStorageARCHIVE)。默认值:STANDARD(QCloudCOSStorageStandard) 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 *

示例

QCloudPutObjectRequest* put = [QCloudPutObjectRequest new];
put.object = @"text.txt";
put.bucket = @"examplebucket-1250000000";
put.body =  [@"testFileContent" dataUsingEncoding:NSUTF8StringEncoding];
[put setFinishBlock:^(id outputObject, NSError *error) {
   //完成回调
  //可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
  if (nil == error) {
   //成功
   }
   }];
[[QCloudCOSXMLService defaultCOSXML] PutObject:put];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

获取对象元数据

功能说明

查询存储桶中是否存在指定的对象(Head Object)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudHeadObjectRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudHeadObjectRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 HeadObject 方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudHeadObjectRequest 参数说明

参数名称 描述 类型 必填
Object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/text.txt 中,对象键为 doc/text.txt。更详细的描述可以参考 对象描述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
ifModifiedSince 如果文件修改时间晚于指定时间,才返回文件内容。否则返回 304 (not modified) NSString *

示例

QCloudHeadObjectRequest* headerRequest = [QCloudHeadObjectRequest new];
headerRequest.object = @"text.txt";
headerRequest.bucket = @"examplebucket-1250000000";

__block id resultError;
[headerRequest setFinishBlock:^(NSDictionary* result, NSError *error) {
      resultError = error;
}];
[[QCloudCOSXMLService defaultCOSXML] HeadObject:headerRequest];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

获取对象

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象名 NSString *
range RFC 2616 中定义的指定文件下载范围,以字节(bytes)为单位 NSString *
ifModifiedSince 如果文件修改时间晚于指定时间,才返回文件内容。否则返回 412 (not modified) NSString *
responseContentType 设置响应头部中的 Content-Type 参数 NSString *
responseContentLanguage 设置响应头部中的 Content-Language 参数 NSString *
responseContentExpires 设置响应头部中的 Content-Expires 参数 NSString *
responseCacheControl 设置响应头部中的 Cache-Control 参数 NSString *
responseContentDisposition 设置响应头部中的 Content-Disposition 参数。 NSString *
responseContentEncoding 设置响应头部中的 Content-Encoding 参数 NSString *

示例

QCloudGetObjectRequest* request = [QCloudGetObjectRequest new];
//设置下载的路径 URL,如果设置了,文件将会被下载到指定路径中.如果该参数没有设置,那么文件将会被下载至内存里,存放在在 finishBlock 的     outputObject 里。
request.downloadingURL = [NSURL URLWithString:QCloudTempFilePathWithExtension(@"downding")];
request.object = @“text.txt”;
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];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

预请求跨域配置

功能说明

获取预请求跨域配置(Options Object)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudOptionsObjectRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudOptionsObjectRequest,填入需要设置的对象名、存储桶名、模拟跨域访问请求的 http 方法和模拟跨域访问允许的访问来源。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudOptionsObjectRequest 参数说明

参数名称 描述 类型 必填
object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参阅 对象概述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
accessControlRequestMethod 模拟跨域访问的请求HTTP方法 NSArray<NSString*> *
origin 模拟跨域访问允许的访问来源,支持通配符 * , 格式为:协议://域名[:端口]如:http://www.qq.com NSString *
allowedHeader 在发送 OPTIONS 请求时告知服务端,接下来的请求可以使用哪些自定义的 HTTP 请求头部,支持通配符 * NSArray<NSString * > *

示例

QCloudOptionsObjectRequest* request = [[QCloudOptionsObjectRequest alloc] init];
request.bucket =@"examplebucket-1250000000";
request.origin = @"*";
request.accessControlRequestMethod = @"get";
request.accessControlRequestHeaders = @"host";
request.object = @"picture.jpg";
__block id resultError;
[request setFinishBlock:^(id outputObject, NSError* error) {
     resultError = error;
    //可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
 }];

[[QCloudCOSXMLService defaultCOSXML] OptionsObject:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

设置对象复制

将一个对象复制到另一个对象(Put Object - Copy)。

请求示例

  QCloudPutObjectCopyRequest* request = [[QCloudPutObjectCopyRequest alloc] init];
  request.bucket = @"examplebucket-1250000000";
  request.object = @" ";
  [request setFinishBlock:^(QCloudCopyObjectResult * _Nonnull result, NSError * _Nonnull error) {

  }];
  request.objectCopySource = objectCopySource;//源对象所在的路径
  [[QCloudCOSXMLService defaultCOSXML]  PutObjectCopy:request];
参数名称 描述 类型 必填
bucket 目的存储桶名,您可以在 COS 控制台 上面看到,注意存储桶名只能由数字和小写字母组成,并且长度不能超过40个字符,否则会创建失败 NSString *
object 目的文件的对象名,key NSString *
objectCopySource 复制的源文件的路径 NSString *
metadataDirective 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制;假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced NSString *
storageClass 对象的存储级别,枚举值:STANDARD(QCloudCOSStorageStandard),STANDARD_IA(QCloudCOSStorageStandardIA)。默认值:STANDARD(QCloudCOSStorageStandard) QCloudCOSStorageClass

返回结果说明

通过 QCloudCopyObjectResult 返回请求结果。

参数名称 描述 类型
eTag ETag 的值可以用于检查 Object 的内容是否发生变化。 NSString *
lastModified 文件的最后修改时间,GMT格式 NSString *
versionID 对象对应的Version ID(在开启了多版本的情况才有) NSString *

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

删除单个对象

功能说明

删除单个对象(Delete Object)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudDeleteObjectRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudDeleteObjectRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudDeleteObjectRequest 参数说明

参数名称 类型 必填 描述
object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg,详情请参阅 对象概述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *

示例

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 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

删除多个对象

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudDeleteMultipleObjectRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudDeleteMultipleObjectRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudDeleteMultipleObjectRequest 参数说明

参数名称 描述 类型 必填
object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参阅 对象概述 NSString *
deleteObjects 封装了需要批量删除的多个对象的信息 QCloudDeleteInfo *

QCloudDeleteInfo参数说明

参数名称 描述 类型 必填
objects 存放需要删除对象信息的数组 NSArray<QCloudDeleteObjectInfo * > *

QCloudDeleteObjectInfo 参数说明

参数名称 描述 类型 必填
key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg,详情请参阅 对象概述 NSString *

示例

QCloudDeleteMultipleObjectRequest* delteRequest = [QCloudDeleteMultipleObjectRequest new];
delteRequest.bucket = @"examplebucket-1250000000";

QCloudDeleteObjectInfo* deletedObject0 = [QCloudDeleteObjectInfo new];
deletedObject0.key = @"text,txt";

QCloudDeleteObjectInfo* deleteObject1 = [QCloudDeleteObjectInfo new];
deleteObject1.key = @"picture.jpg";

QCloudDeleteInfo* deleteInfo = [QCloudDeleteInfo new];
deleteInfo.quiet = NO;
deleteInfo.objects = @[ deletedObject0,deleteObject2];
delteRequest.deleteObjects = deleteInfo;
__block NSError* resultError;
[delteRequest setFinishBlock:^(QCloudDeleteResult* outputObject, NSError *error) {
      localError = error;
      deleteResult = outputObject;
}];
[[QCloudCOSXMLService defaultCOSXML] DeleteMultipleObject:delteRequest];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的error里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

分块操作

查询分片上传

功能说明

查询指定存储桶中正在进行的分片上传。

方法原型

进行存储桶操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudListBucketMultipartUploadsRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudListBucketMultipartUploadsRequest,填入需要的参数,如返回结果的前缀、编码方式等。
  2. 调用 QCloudCOSXMLService 对象中的 ListBucketMultipartUploads 方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudListBucketMultipartUploadsRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
prefix 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix NSString *
delimiter 定界符为一个符号,如果有 Prefix,则将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix,然后列出所有 Common Prefix。如果没有 Prefix,则从路径起点开始。可以将其理解为结束的符号,例如如果想要结尾是 A 的结果,那么将delimiter设置为 A 即可。 NSString *
encodingType 规定返回值的编码方式,可选值:url NSString *
keyMarker 列出条目从该 key 值开始 NSString *
uploadIDMarker 列出条目从该 UploadId 值开始 int
maxUploads 设置最大返回的 multipart 数量,合法值1到1000 int

返回结果 QCloudListMultipartUploadsResult 参数说明

参数名称 描述 类型
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
prefix 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix NSString *
delimiter 定界符为一个符号,如果有 Prefix,则将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix,然后列出所有 Common Prefix。如果没有 Prefix,则从路径起点开始 NSString *
encodingType 规定返回值的编码方式,可选值:url NSString *
keyMarker 列出条目从该 key 值开始 NSString *
maxUploads 设置最大返回的 multipart 数量,合法值1到1000 int
uploads 所有已经上传的分片信息 NSArray*

示例

QCloudListBucketMultipartUploadsRequest* uploads = [QCloudListBucketMultipartUploadsRequest new];
uploads.bucket = @"examplebucket-1250000000";
uploads.maxUploads = 100;
__block NSError* resulError;
__block QCloudListMultipartUploadsResult* multiPartUploadsResult;
[uploads setFinishBlock:^(QCloudListMultipartUploadsResult* result, NSError *error) {
    multiPartUploadsResult = result;
    localError = error;
}];
[[QCloudCOSXMLService defaultCOSXML] ListBucketMultipartUploads:uploads];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。返回错误码(封装在返回的error里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码由苹果公司定义,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

分片上传对象

分片上传对象可包括的操作:

  • 分片上传对象: 初始化分片上传, 上传分片块, 完成所有分片块上传。
  • 分片续传:查询已上传的分片块, 上传分片块,完成所有分片块上传。
  • 删除已上传分片块。

初始化分片上传

功能说明

初始化分片上传,获取对应的 uploadId(Initiate Multipart Upload)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudInitiateMultipartUploadRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudInitiateMultipartUploadRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 InitiateMultipartUpload 方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

参数说明

参数名称 描述 类型 必填
Object 上传文件(对象)的文件名,也是对象的key。 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg。更详细的描述可以参考 对象描述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
cacheControl RFC 2616中定义的缓存策略 NSString *
contentDisposition RFC 2616中定义的文件名称 NSString *
expect 当使用 expect=@"100-continue"时,在收到服务端确认后才会发送请求内容 NSString *
expires RFC 2616 中定义的过期时间 NSString *
storageClass 对象的存储级别,枚举值:STANDARD(QCloudCOSStorageStandard),STANDARD_IA(QCloudCOSStorageStandardIA),ARCHIVE(QCloudCOSStorageARCHIVE)。默认值:STANDARD(QCloudCOSStorageStandard) QCloudCOSStorageClass
accessControlList 定义 Object 的 ACL 属性。有效值:private,public-read;默认值:private NSString *
grantRead 赋予被授权者读的权限。格式:id="[OwnerUin]" NSString *
grantWrite 授予被授权者写的权限。格式同上。 NSString *
grantFullControl 授予被授权者读写权限。格式同上。 NSString *

示例

QCloudInitiateMultipartUploadRequest* initrequest = [QCloudInitiateMultipartUploadRequest new];
initrequest.bucket = @"examplebucket-1250000000";
initrequest.object = @"text.txt";
__block QCloudInitiateMultipartUploadResult* initResult;
[initrequest setFinishBlock:^(QCloudInitiateMultipartUploadResult* outputObject, NSError *error) {
    initResult = outputObject;
}];
[[QCloudCOSXMLService defaultCOSXML] InitiateMultipartUpload:initrequest];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

上传分块

功能说明

分块上传文件。

QCloudUploadPartRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象的名称 NSString *
uploadId 标识本次分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 NSString *
partNumber 标识本次分块上传的编号 int
contentSHA1 本次分片上传的 sha1 值 NSString *
body 上传的数据:支持 NSData*,NSURL(本地 URL)和 QCloudFileOffsetBody* 三种类型 BodyType

返回结果 QCloudUploadPartResult 参数说明

参数名称 描述 类型
eTag 文件的 etag NSString *

方法原型

COS iOS SDK 中分块上传请求的方法具体步骤如下:

  1. 实例化 QCloudUploadPartRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 UploadPart 方法发出请求。
  3. 从回调的 finishBlock 中的 QCloudUploadPartResult 获取具体内容。

示例

QCloudUploadPartRequest* request = [QCloudUploadPartRequest new];
request.bucket = @"examplebucket-1250000000";
request.object = @"text.txt";
request.partNumber = @"partNumber"
request.uploadId = @"uploadId"; //标识本次分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置
request.body = body;//上传的数据:支持NSData*,NSURL(本地url)和QCloudFileOffsetBody *三种类型  
[request setSendProcessBlock:^(int64_t bytesSent,
                                    int64_t totalBytesSent,
                                    int64_t totalBytesExpectedToSend) {
}];
[request setFinishBlock:^(QCloudUploadPartResult* outputObject, NSError *error) {
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSXMLService defaultCOSXML]  UploadPart:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

复制分块

功能说明

分块复制文件。

QCloudUploadPartRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象的名称 NSString *
uploadId 标识本次分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 NSString *
partNumber 标识本次分块上传的编号 int
source 源文件 URL 路径,可以通过 versionid 子资源指定历史版本 NSString *
body 上传的数据:支持 NSData*,NSURL(本地 URL)和 QCloudFileOffsetBody* 三种类型 BodyType

返回结果 QCloudUploadPartResult 参数说明

参数名称 描述 类型
eTag 文件的 etag NSString *

方法原型

COS iOS SDK 中分块上传请求的方法具体步骤如下:

  1. 实例化 QCloudUploadPartCopyRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 UploadPartCopy 方法发出请求。
  3. 从回调的 finishBlock 中的 QCloudCopyObjectResult 获取具体内容。

示例

QCloudUploadPartCopyRequest* request = [[QCloudUploadPartCopyRequest alloc] init];
request.bucket = @"examplebucket-1250000000";
request.object = @"text.txt";
request.source = @"objectCopySource"; //  源文件 URL 路径,可以通过 versionid 子资源指定历史版本
request.uploadID = @"uploadID"; // 在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID)
request.partNumber = 1; // 标志当前分块的序号
[request setFinishBlock:^(QCloudCopyObjectResult* result, NSError* error) {
}];
[[QCloudCOSXMLService defaultCOSXML]UploadPartCopy:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

查询已上传块

功能说明

查询指定 uploadId 已上传的分片块(List Parts)。

QCloudListMultipartRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象的名称 NSString *
uploadId 本次要查询的分块上传的uploadId NSString *
maxPartsCount 单次返回最大的条目数量,默认1000 NSString *
partNumberMarker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 NSString *
encodingType 规定返回值的编码方式 int

返回结果 QCloudListPartsResult 参数说明

参数名称 描述 类型
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
encodingType 限规定返回值的编码格式 NSString *
key 对象的名称 NSString *
uploadId 本次查询的分块上传的 uploadId NSString *
storageClass 用来表示这些分块的存储级别 QCloudCOSStorageClass
partNumberMarker 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 int
nextNumberMarker 假如返回条目被截断,则返回 NextMarker 就是下一个条目的起点 NSString *
maxParts 单次返回的最大条目数 QCloudCOSStorageClass
isTruncated 返回条目是否被截断 BOOL
initiator 用来标识本次上传发起者的信息 NSString *
owner 用来标识这些分块所有者的信息 QCloudCOSStorageClass
parts 用来表示每一个块的信息 QCloudMultipartUploadPart*

示例

  QCloudListMultipartRequest* request = [QCloudListMultipartRequest new];
  request.object = @"text.txt"
  request.bucket = @"examplebucket-1250000000";
  request.uploadId = @"uploadId";//本次要查询的分块上传的uploadId,可从初始化分片上传的请求结果QCloudInitiateMultipartUploadResult中得到
  [request setFinishBlock:^(QCloudListPartsResult * _Nonnull result,
                              NSError * _Nonnull error) {
  }];

  [[QCloudCOSXMLService defaultCOSXML] ListMultipart:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

完成分片上传

功能说明

实现完成整个分块上传(Complete Multipart Upload)。

QCloudCompleteMultipartUploadRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象的名称 NSString *
uploadId 标识本次分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 NSString *
parts 完成分片上传的信息 QCloudCompleteMultipartUploadInfo *

返回结果 QCloudUploadObjectResult 参数说明

参数名称 描述 类型
location 创建对象的外网访问域名 NSString *
bucket 分块上传的目标存储桶名: 可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
key 对象名 NSString *
eTag 合并后文件的 MD5 算法校验值 NSString *
versionID 对象对应的 Version ID(在开启了多版本的情况才有) NSString *

方法原型

COS iOS SDK 中完成整个分块上传请求的方法具体步骤如下:

  1. 实例化 QCloudCompleteMultipartUploadRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 CompleteMultipartUpload 方法发出请求。
  3. 从回调的 finishBlock 中的 QCloudUploadObjectResult 获取具体内容。

示例

QCloudCompleteMultipartUploadRequest *completeRequst = [QCloudCompleteMultipartUploadRequest new];
completeRequst.bucket = @"examplebucket-1250000000";
completeRequst.object = @"text.txt";
completeRequst.uploadId = @"uploadId"; //本次分片上传的UploadID
[completeRequst setFinishBlock:^(QCloudUploadObjectResult * _Nonnull result, NSError * _Nonnull error) {

}];
[[QCloudCOSXMLService defaultCOSXML] CompleteMultipartUpload:completeRequst];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

终止分块上传

功能说明

舍弃一个分块上传并删除已上传的块(Abort Multipart Upload)。

QCloudAbortMultipfartUploadRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名称,可在 COS V5 控制台 上面看到,命名格式:BucketName-APPID。例如 examplebucket-1250000000 NSString *
object 对象的名称 NSString *
uploadId 要丢弃的分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分片上传时会得到一个 uploadId,该 ID 不但唯一标识这一分块数据,也标识了这分块数据在整个文件内的相对位置 NSString *

方法原型

cos iOS SDK 中舍弃一个分块上传且删除已上传的分片块请求的方法具体步骤如下:

  1. 实例化 QCloudAbortMultipfartUploadRequest,填入需要的参数。
  2. 调用 QCloudCOSXMLService 对象中的 AbortMultipfartUpload 方法发出请求。
  3. 从回调的 finishBlock 中的 outputObject 获取具体内容。

示例

QCloudAbortMultipfartUploadRequest *abortRequest = [QCloudAbortMultipfartUploadRequest new];
abortRequest.bucket = @"examplebucket-1250000000"; // 存储桶名称,命名格式:BucketName-APPID
abortRequest.object = @"text.txt";
abortRequest.uploadId = @"uploadId";
[abortRequest setFinishBlock:^(id outputObject, NSError *error) {
//additional actions after finishing
//可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSXMLService defaultCOSXML]AbortMultipfartUpload:abortRequest];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

其他操作

恢复归档对象

功能说明

恢复归档对象(POST Object restore)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudPostObjectRestoreRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudPostObjectRestoreRequest,填入需要设置的对象名、存储桶名。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中的获取具体内容。

QCloudPostObjectRestoreRequest 参数说明

参数名称 描述 类型 必填
object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/picture.jpg 中,对象键为 doc/picture.jpg。更详细的描述可以参考 对象描述 NSString *
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
restoreRequest 模恢复数据的配置信息 QCloudRestoreRequest *

QCloudRestoreRequest 参数说明

参数名称 描述 类型 必填
days 设置临时副本的过期时间 int64_t
CASJobParameters 复原的过程类型配置信息 CASJobParameters *

CASJobParameters 参数说明

参数名称 描述 类型 必填
tier 恢复模式,支持的三种恢复模式,分别为 Standard(标准模式,恢复任务在35小时内完成)、Expedited(极速模式,恢复任务在15分钟内可完成)以及 Bulk(批量模式,恢复任务在5 - 12小时内完成) QCloudCASTier

示例

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

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

设置对象 ACL

功能说明

设置对象访问权限控制列表(ACL)。

方法原型

进行对象操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudPutObjectACLRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudPutObjectACLRequest,填入存储桶名,和一些额外需要的参数,如授权的具体信息等。
  2. 调用 QCloudCOSXMLService 对象中的方法发出请求。
  3. 从回调的 finishBlock 中获取设置的完成情况,若 error 为空,则设置成功。

QCloudPutObjectACLRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象名称 NSString *
accessControlList 定义 Object 的 ACL 属性。有效值:private,public-read;默认值:private NSString *
grantRead 赋予被授权者读的权限。格式:id="[OwnerUin]" NSString *
grantWrite 授予被授权者写的权限。格式同上 NSString *
grantFullControl 授予被授权者读写权限。格式同上 NSString *

示例

QCloudPutObjectACLRequest* request = [QCloudPutObjectACLRequest new];
request.object = @"text.txt";
request.bucket = @"examplebucket-1250000000";
NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
request.grantFullControl = grantString;
__block NSError* localError;
[request setFinishBlock:^(id outputObject, NSError *error) {
     localError = error;
    //可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息(更多头部信息可以通过打印 outputObject 查看)
}];
[[QCloudCOSXMLService defaultCOSXML] PutObjectACL:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

获取对象 ACL

功能说明

获取对象访问权限控制列表(ACL)。

方法原型

进行文件操作之前,需要导入头文件 QCloudCOSXML/QCloudCOSXML.h。在此之前您需要完成 初始化操作。先生成一个 QCloudGetObjectACLRequest 实例,然后填入一些需要的额外限制条件,通过并获得内容。具体步骤如下:

  1. 实例化 QCloudGetObjectACLRequest,填入存储桶的名称,和需要查询对象的名称。
  2. 调用 QCloudCOSXMLService 对象中的 GetObjectACL 方法发出请求。
  3. 从回调的 finishBlock 中的获取的 QCloudACLPolicy 对象中获取封装好的 ACL 的具体信息。

QCloudGetObjectACLRequest 参数说明

参数名称 描述 类型 必填
bucket 存储桶名,可在 COS V5 控制台 上面看到,格式为<BucketName-APPID> ,例如 examplebucket-1250000000 NSString *
object 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg。更详细的描述可以参考 对象描述 NSString *

示例

QCloudGetObjectACLRequest *request = [QCloudGetObjectACLRequest new];
request.object = @"text.txt";
request.bucket = @"examplebucket-1250000000"
__block QCloudACLPolicy* policy;
[request setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
     policy = result;
}];
[[QCloudCOSXMLService defaultCOSXML] GetObjectACL:request];

返回错误码说明

当 SDK 请求失败的时候,返回的 error 将不为空,并且包括了错误码、错误描述和其它一些调试必备的信息,以帮助开发者快速解决问题。

返回错误码(封装在返回的 error 里)主要包括两类:设备本身因为网络原因等返回的错误码,以及 COS 返回的错误码。

  • 对于设备本身因为网络原因产生的错误码,都是负数并且是四位数,例如-1001,这类错误码是苹果定义的,可以参考 Foundation 框架中的 NSURLError.h 头文件内的定义,或者是 苹果官方文档说明
  • 对于 COS 返回的错误码,是基于 HTTP 的状态码而来的,也就是404,503这类。对于这类错误码,可以参考 错误码 文档寻求解决方案。
  • 对于 SDK 自定义的错误码,均为5位数且都是正数,如10000、20000等。对于这类错误码,可以参考 SDK 错误码 文档寻求解决方案。

加入自定义头部

如果有需要加入自定义头部的需求,可以使用自定义头部。支持加入自定义头部的类,都会有 customHeaders 这个属性:

@property (strong, nonatomic) NSMutableDictionary* customHeaders;

对于所有该属性内的键值对,都会以对应的形式加入到构建请求的 HTTP 头部中。

服务器加密

如果需要对上传的对象进行加密,我们支持以下加密方式。

使用 COS 托管加密密钥的服务端加密(SSE-COS)保护数据

COS 会帮助您在数据写入数据中心时自动加密,并在您取用该数据时自动解密。目前支持使用 COS 主密钥对数据进行 AES-256 加密。

iOS SDK 通过调用 -(void)setCOSServerSideEncyption 方法来完成。

[request setCOSServerSideEncyption];

使用客户提供的加密密钥的服务器端加密 (SSE-C)保护数据

iOS SDK 通过调用 -(void)setCOSServerSideEncyptionWithCustomerKey:(NSString *)customerKey 方法来完成。

注意:

  • 该加密所运行的服务需要使用 HTTPS 请求。
  • customerKey:用户提供的密钥,传入一个32字节的字符串,支持数字、字母、字符的组合,不支持中文。
  • 如果上传的源文件调用了该方法,那么在使用 QCloudCOSXMLDownloadObjectRequest(下载)、QCloudHeadObjectRequest(查询)、QCloudCOSXMLUploadObjectReques(上传)、QCloudCOSXMLUploadObjectRequest(copy)对源对象操作的时候也要调用该方法。
NSString *customKey = @"123456qwertyuioplkjhgfdsazxcvbnm";
[put setCOSServerSideEncyptionWithCustomerKey:customKey];