接口文档

说明：

在接口文档中，我们假设您已经完成了初始化的过程。接口文档重点在于列出详细的接口列表，并且举例如何使用。查询时建议Control+F搜索到想要查询的接口，然后看我们给出的接口简单说明，复制示例到您的工程中运行。 如果需要更多的功能，或者不明白返回的参数是什么意义，建议直接查看代码里的注释，可以三指轻按、Force-touch重按或者将鼠标停留在变量上，按Control+Command+D查看它的释义。

Service 操作

列出所有Bucket - Get Service

Get Service 接口是用来获取请求者名下的所有存储空间列表（Bucket list）。

返回结果QCloudListAllMyBucketsResult参数说明

示例

    QCloudGetServiceRequest* request = [[QCloudGetServiceRequest alloc] init];
    [request setFinishBlock:^(QCloudListAllMyBucketsResult* result, NSError* error) {
      //
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetService:request];

存储桶操作

列举存储桶内的内容

方法原型

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

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

QCloudGetBucketRequest 参数说明

示例

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

获取存储桶的 ACL（Access Control List）

方法原型

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

1. 实例化 QCloudGetBucketACLRequest，填入获取 ACL 的存储桶。
2. 调用 QCloudCOSXMLService 对象中的 GetBucketACL 方法发出请求。
3. 从回调的 finishBlock 中的 QCloudACLPolicy 获取具体内容。

QCloudGetBucketACLRequest 参数说明

返回结果 QCloudACLPolicy 参数说明

示例

  QCloudGetBucketACLRequest* getBucketACl   = [QCloudGetBucketACLRequest new];
    getBucketACl.bucket = @"testbucket-123456789";
    [getBucketACl setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
        //QCloudACLPolicy中包含了 Bucket 的 ACL 信息。
    }];

    [[QCloudCOSXMLService defaultCOSXML] GetBucketACL:getBucketACl];

设置存储桶的 ACL(Access Control List)

方法原型

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

1. 实例化 QCloudPutBucketACLRequest，填入需要设置的存储桶，然后根据设置值的权限类型分别填入不同的参数。
2. 调用 QCloudCOSXMLService 对象中的 PutBucketACL 方法发出请求。
3. 从回调的 finishBlock 中的获取设置是否成功，并做设置成功后的一些额外动作。

QCloudPutBucketACLRequest 参数说明

示例

    QCloudPutBucketACLRequest* putACL = [QCloudPutBucketACLRequest new];
    NSString* appID = @“您的 APP ID”;
    NSString *ownerIdentifier = [NSString stringWithFormat:@"qcs::cam::uin/%@:uin/%@", appID, appID];
    NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
    putACL.grantFullControl = grantString;
    putACL.bucket = @“testBucket-123456789”;
    [putACL setFinishBlock:^(id outputObject, NSError *error) {
    //error occucs if error != nil
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketACL:putACL];

获取存储桶的 CORS(跨域访问)设置

方法原型

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

1. 实例化 QCloudPutBucketCORSRequest，填入需要获取 CORS 的存储桶。
2. 调用 QCloudCOSXMLService 对象中的 GetBucketCORS 方法发出请求。
3. 从回调的 finishBlock 中获取结果。结果封装在了 QCloudCORSConfiguration 对象中，该对象的 rules 属性是一个数组，数组里存放着一组 QCloudCORSRule，具体的 CORS 设置就封装在 QCloudCORSRule 对象里。

QCloudPutBucketCORSRequest 参数说明

返回结果 QCloudCORSConfiguration 参数说明

QCloudCORSRule 参数说明

示例

    QCloudGetBucketCORSRequest* corsReqeust = [QCloudGetBucketCORSRequest new];
    corsReqeust.bucket = @"testBucket-123456789";

    [corsReqeust setFinishBlock:^(QCloudCORSConfiguration * _Nonnull result, NSError * _Nonnull error) {
        //CORS设置封装在result中。
      }];

    [[QCloudCOSXMLService defaultCOSXML] GetBucketCORS:corsReqeust];

设置存储桶的 CORS（跨域访问）

方法原型

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

1. 实例化 QCloudPutBucketCORSRequest，设置存储桶，并且将需要的 CORS 装入 QCloudCORSRule 中，如果有多组 CORS 设置，可以将多个 QCloudCORSRule 放在一个 NSArray 里，然后将该数组填入 QCloudCORSConfiguration的rules 属性里，放在 request 中。
2. 调用 QCloudCOSXMLService 对象中的 PutBucketCORS 方法发出请求。
3. 从回调的 finishBlock 中的获取设置成功与否（error 是否为空），并且做一些设置后的额外动作。

QCloudPutBucketCORSRequest 参数说明

QCloudCORSConfiguration 参数说明

QCloudCORSRule 参数说明

示例

    QCloudPutBucketCORSRequest* putCORS = [QCloudPutBucketCORSRequest new];
    QCloudCORSConfiguration* cors = [QCloudCORSConfiguration new];

    QCloudCORSRule* rule = [QCloudCORSRule new];
    rule.identifier = @"sdk";
    rule.allowedHeader = @[@"origin",@"host",@"accept",@"content-type",@"authorization"];
    rule.exposeHeader = @"ETag";
    rule.allowedMethod = @[@"GET",@"PUT",@"POST", @"DELETE", @"HEAD"];
    rule.maxAgeSeconds = 3600;
    rule.allowedOrigin = @"*";

    cors.rules = @[rule];

    putCORS.corsConfiguration = cors;
    putCORS.bucket = @"testBucket-123456789";
    [putCORS setFinishBlock:^(id outputObject, NSError *error) {
        if (!error) {
        //success
        }
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketCORS:putCORS];

获取存储桶的地域信息

方法原型

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

1. 实例化 QCloudGetBucketLocationRequest，填入 Bucket 名。
2. 调用 QCloudCOSXMLService 对象中的 GetBucketLocation 方法发出请求。
3. 从回调的 finishBlock 中的获取具体内容。

QCloudGetBucketLocationRequest 参数说明

返回结果 QCloudBucketLocationConstraint 参数说明

示例

  QCloudGetBucketLocationRequest* locationReq = [QCloudGetBucketLocationRequest new];
    locationReq.bucket = @"testBucket-123456789";
    __block QCloudBucketLocationConstraint* location;
    [locationReq setFinishBlock:^(QCloudBucketLocationConstraint * _Nonnull result, NSError * _Nonnull error) {
        location = result;
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucketLocation:locationReq];

删除存储桶 CORS 设置

方法原型

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

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

QCloudDeleteBucketCORSRequest 参数说明

示例

 QCloudDeleteBucketCORSRequest* deleteCORS = [QCloudDeleteBucketCORSRequest new];
    deleteCORS.bucket = @"testBucket-123456789";
    [deleteCORS setFinishBlock:^(id outputObject, NSError *error) {
        //success if error == nil
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteBucketCORS:deleteCORS];

查询 Bucket 中正在进行的分块上传

方法原型

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

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

QCloudListBucketMultipartUploadsRequest 参数说明

返回结果 QCloudListMultipartUploadsResult 参数说明

示例

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

Head Bucket

Head Bucket 请求可以确认该 Bucket 是否存在，是否有权限访问。Head 的权限与 Read 一致。当该 Bucket 存在时，返回200；当该 Bucket 无访问权限时，返回 403；当该 Bucket 不存在时，返回 404。

QCloudHeadBucketRequest 参数说明

示例

QCloudHeadBucketRequest* request = [QCloudHeadBucketRequest new];
 request.bucket = @"testBucket-123456789";
 [request setFinishBlock:^(id outputObject, NSError* error) {
     //设置完成回调。如果没有error，则可以正常访问bucket。如果有error，可以从error code和messasge中获取具体的失败原因。
 }];
 [[QCloudCOSXMLService defaultCOSXML] HeadBucket:request];

文件操作

在 CSP 中，每个文件就是一个 Object（对象）。对文件的操作，其实也就是对对象的操作。

简单上传 (Put Object)

简单上传仅限于小文件（20MB以下）。简单上传支持从内存中上传文件。

QCloudPutObjectRequest 参数说明

示例

QCloudPutObjectRequest* put = [QCloudPutObjectRequest new];
put.object = @"object-name";
put.bucket = @"bucket-12345678";
put.body =  [@"testFileContent" dataUsingEncoding:NSUTF8StringEncoding];
[put setFinishBlock:^(id outputObject, NSError *error) {
    //完成回调
    if (nil == error) {
      //成功
    }
}];
[[QCloudCOSXMLService defaultCOSXML] PutObject:put];

查询对象的 ACL（Access Control List）

方法原型

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

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

QCloudGetObjectACLRequest 参数说明

示例

 request.bucket = self.aclBucket;
    request.object = @"对象的名称";
    request.bucket = @"testBucket-123456789"
    __block QCloudACLPolicy* policy;
    [request setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
        policy = result;
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObjectACL:request];

设置对象的 ACL（Access Control List）

方法原型

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

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

QCloudPutObjectACLRequest 参数说明

示例

    QCloudPutObjectACLRequest* request = [QCloudPutObjectACLRequest new];
    request.object = @"需要设置 ACL 的对象名";
    request.bucket = @"testBucket-123456789";
    NSString *ownerIdentifier = [NSString stringWithFormat:@"qcs::cam::uin/%@:uin/%@",self.appID, self.appID];
    NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
    request.grantFullControl = grantString;
    __block NSError* localError;
    [request setFinishBlock:^(id outputObject, NSError *error) {
        localError = error;
    }];

    [[QCloudCOSXMLService defaultCOSXML] PutObjectACL:request];

下载文件

方法原型

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

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

参数说明

示例

  QCloudGetObjectRequest* request = [QCloudGetObjectRequest new];
  //设置下载的路径 URL，如果设置了，文件将会被下载到指定路径中
  request.downloadingURL = [NSURL URLWithString:QCloudTempFilePathWithExtension(@"downding")];
  request.object = @“你的 Object-Key”;
  request.bucket = @"testBucket-123456789";
  [request setFinishBlock:^(id outputObject, NSError *error) {
    //additional actions after finishing
}];
    [request setDownProcessBlock:^(int64_t bytesDownload, int64_t totalBytesDownload, int64_t totalBytesExpectedToDownload) {
     //下载过程中的进度
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObject:request];

Object 跨域访问配置的预请求

方法原型

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

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

QCloudOptionsObjectRequest 参数说明

示例

 QCloudOptionsObjectRequest* request = [[QCloudOptionsObjectRequest alloc] init];
    request.bucket =@"存储桶名";
    request.origin = @"*";
    request.accessControlRequestMethod = @"get";
    request.accessControlRequestHeaders = @"host";
    request.object = @"对象名";
    __block id resultError;
    [request setFinishBlock:^(id outputObject, NSError* error) {
        resultError = error;
    }];

    [[QCloudCOSXMLService defaultCOSXML] OptionsObject:request];

删除单个对象

方法原型

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

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

QCloudDeleteObjectRequest 参数说明

示例

QCloudDeleteObjectRequest* deleteObjectRequest = [QCloudDeleteObjectRequest new];
    deleteObjectRequest.bucket = @"testBucket-123456789";
    deleteObjectRequest.object = @"对象名";

    __block NSError* resultError;
    [deleteObjectRequest setFinishBlock:^(id outputObject, NSError *error) {
        resultError = error;
    }];
    [[QCloudCOSXMLService defaultCOSXML] DeleteObject:deleteObjectRequest];

删除多个对象

方法原型

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

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

QCloudDeleteMultipleObjectRequest 参数说明

QCloudDeleteInfo参数说明

QCloudDeleteObjectInfo 参数说明

示例

QCloudDeleteMultipleObjectRequest* delteRequest = [QCloudDeleteMultipleObjectRequest new];
    delteRequest.bucket = @"testBucket-123456789";

    QCloudDeleteObjectInfo* deletedObject0 = [QCloudDeleteObjectInfo new];
    deletedObject0.key = @"第一个对象名";

    QCloudDeleteObjectInfo* deleteObject1 = [QCloudDeleteObjectInfo new];
    deleteObject1.key = @"第二个对象名";

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

初始化分片上传

方法原型

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

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

参数说明

示例

QCloudInitiateMultipartUploadRequest* initrequest = [QCloudInitiateMultipartUploadRequest new];
    initrequest.bucket = @"testBucket-123456789";
    initrequest.object = @"对象名";
    __block QCloudInitiateMultipartUploadResult* initResult;
    [initrequest setFinishBlock:^(QCloudInitiateMultipartUploadResult* outputObject, NSError *error) {
        initResult = outputObject;
    }];
    [[QCloudCOSXMLService defaultCOSXML] InitiateMultipartUpload:initrequest];

获取对象meta信息

方法原型

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

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

QCloudHeadObjectRequest 参数说明

示例

QCloudHeadObjectRequest* headerRequest = [QCloudHeadObjectRequest new];
    headerRequest.object = @“对象名”;
    headerRequest.bucket = @"testBucket-123456789";

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

    [[QCloudCOSXMLService defaultCOSXML] HeadObject:headerRequest];

服务器端加密(Server side encryption)说明

CSP支持服务器端加密(Server side encryption)，该特性的作用是object在上传到CSP后会进行服务器端加密，然后再存储。下载时候会拿出原始没有解密的数据，进行解密后返回。这个过程对客户端是透明的，无需关心具体的加密过程。

如果需要使用该特性，那么在上传object时，需要在上传HTTP请求中加入一个额外的头部，key为 x-cos-server-side-encryption, 值为AES256。在下载时候直接照常GetObject即可。

利用SDK中自定义头部的功能可以实现这一需求。只需要在上传请求中加入自定义头部即可：

   QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
   __block NSString* object = [NSUUID UUID].UUIDString;
   put.object = @"object";
   put.bucket = @"存储桶名";
   put.body =  @"文件在本地的URL";
   put.customHeaders = @{@"x-cos-server-side-encryption":@"AES256"};
   [put setFinishBlock:^(QCloudUploadObjectResult *result, NSError *error) {
     //完成回调
   }];
   [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

下载时候无需关心加解密过程：

QCloudGetObjectRequest* getObjectRequest = [[QCloudGetObjectRequest alloc] init];
       getObjectRequest.bucket = self.bucket;
       getObjectRequest.object = object;
       NSURL* downloadPath = @“下载到本地的路径”;
       getObjectRequest.downloadingURL = downloadPath;
       [getObjectRequest setFinishBlock:^(id outputObject, NSError *error) {
         //完成回调
       }];
       [[QCloudCOSXMLService defaultCOSXML] GetObject:getObjectRequest];