上传与复制对象

最后更新时间:2020-09-09 11:39:12

    简介

    本文档提供关于对象的上传、复制操作相关的 API 概览以及 SDK 示例代码。

    简单操作

    API 操作名 操作描述
    PUT Object 简单上传对象 上传一个对象至存储桶
    POST Object 表单上传对象 使用表单请求上传对象
    PUT Object - Copy 设置对象复制(修改对象属性) 复制文件到目标路径

    分块操作

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

    SDK API 参考

    SDK 所有接口的具体参数与方法说明,请参考 SDK API

    高级接口(推荐)

    上传对象

    高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持续传功能。

    示例代码一: 上传本地文件

    Objective-C

    QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
    // 本地文件路径
    NSURL* url = [NSURL fileURLWithPath:@"文件的URL"];
    
    // 存储桶名称,格式为 BucketName-APPID
    put.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    put.object = @"exampleobject";
    
    // 需要上传的对象内容。可以传入NSData*或者NSURL*类型的变量
    put.body =  url;
    // 监听上传进度
    [put setSendProcessBlock:^(int64_t bytesSent,
                               int64_t totalBytesSent,
                               int64_t totalBytesExpectedToSend) {
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    }];
    
    // 监听上传结果
    [put setFinishBlock:^(id outputObject, NSError *error) {
        // 可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息
        NSDictionary * result = (NSDictionary *)outputObject;
    }];
    
    [put setInitMultipleUploadFinishBlock:^(QCloudInitiateMultipartUploadResult *
                                            multipleUploadInitResult,
                                            QCloudCOSXMLUploadObjectResumeData resumeData) {
        // 在初始化分块上传完成以后会回调该 block,在这里可以获取 resumeData,uploadid
        NSString* uploadId = multipleUploadInitResult.uploadId;
    }];
    
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    Swift

    let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
    
    // 存储桶名称,格式为 BucketName-APPID
    put.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    put.object = "exampleobject";
    
    // 需要上传的对象内容。可以传入NSData*或者NSURL*类型的变量
    put.body = NSURL.fileURL(withPath: "Local File Path") as AnyObject;
    
    // 监听上传结果
    put.setFinish { (result, error) in
        // 获取上传结果
        if let result = result {
            // 文件的 etag
            let eTag = result.eTag
        } else {
            print(error!);
        }
    }
    
    // 监听上传进度
    put.sendProcessBlock = { (bytesSent, totalBytesSent,
        totalBytesExpectedToSend) in
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    };
    // 设置上传参数
    put.initMultipleUploadFinishBlock = {(multipleUploadInitResult, resumeData) in
        // 在初始化分块上传完成以后会回调该 block,在这里可以获取 resumeData,以及 uploadId
        if let multipleUploadInitResult = multipleUploadInitResult {
            let uploadId = multipleUploadInitResult.uploadId
        }
    }
    
    QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    示例代码二: 上传二进制数据

    Objective-C

    QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
    
    // 存储桶名称,格式为 BucketName-APPID
    put.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    put.object = @"exampleobject";
    
    // 需要上传的对象内容。可以传入NSData*或者NSURL*类型的变量
    put.body = [@"My Example Content" dataUsingEncoding:NSUTF8StringEncoding];
    
    // 监听上传进度
    [put setSendProcessBlock:^(int64_t bytesSent,
                               int64_t totalBytesSent,
                               int64_t totalBytesExpectedToSend) {
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    }];
    
    // 监听上传结果
    [put setFinishBlock:^(id outputObject, NSError *error) {
        // outputObject 包含所有的响应 http 头部
        NSDictionary* info = (NSDictionary *) outputObject;
    }];
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    Swift

    let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
    
    // 存储桶名称,格式为 BucketName-APPID
    put.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    put.object = "exampleobject";
    
    // 需要上传的对象内容
    let dataBody:NSData = "wrwrwrwrwrw".data(using: .utf8)! as NSData;
    put.body = dataBody;
    
    // 监听上传结果
    put.setFinish { (result, error) in
        // 获取上传结果
        if let result = result {
            // 文件的 etag
            let eTag = result.eTag
        } else {
            print(error!);
        }
    }
    
    // 监听上传进度
    put.sendProcessBlock = { (bytesSent, totalBytesSent,
        totalBytesExpectedToSend) in
    
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    };
    
    QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    示例代码三: 上传暂停、继续与取消

    Objective-C

    对于上传任务,可以通过以下方式暂停:

    NSError *error;
    NSData *resmeData = [put cancelByProductingResumeData:&error];

    暂停之后,可以通过以下方式续传:

    QCloudCOSXMLUploadObjectRequest *resumeRequest = [QCloudCOSXMLUploadObjectRequest requestWithRequestData:resmeData];
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:resumeRequest];

    也通过以下方式取消上传:

    //丢弃该上传
    [put abort:^(id outputObject, NSError *error) {
    
    }];

    说明:

    • 更多完整示例,请前往 GitHub 查看。

    Swift

    对于上传任务,可以通过以下方式暂停:

    var error : NSError?;
    var uploadResumeData:Data = put.cancel(byProductingResumeData:&error) as Data;

    暂停之后,可以通过以下方式续传:

    var resumeRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>.init(request: uploadResumeData);
    QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(resumeRequest);

    也通过以下方式取消上传:

    //丢弃该上传
    put.abort { (outputObject, error) in
    
    }

    说明:

    • 更多完整示例,请前往 GitHub 查看。

    示例代码四: 批量上传

    Objective-C

    for (int i = 0; i<20; i++) {
        QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
    
        // 存储桶名称,格式为 BucketName-APPID
        put.bucket = @"examplebucket-1250000000";
    
        // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
        put.object = [NSString stringWithFormat:@"exampleobject-%d",i];
    
        // 需要上传的对象内容。可以传入NSData*或者NSURL*类型的变量
        put.body = [@"My Example Content" dataUsingEncoding:NSUTF8StringEncoding];
    
        // 监听上传进度
        [put setSendProcessBlock:^(int64_t bytesSent,
                                   int64_t totalBytesSent,
                                   int64_t totalBytesExpectedToSend) {
            // bytesSent                   新增字节数
            // totalBytesSent              本次上传的总字节数
            // totalBytesExpectedToSend    本地上传的目标字节数
        }];
    
        // 监听上传结果
        [put setFinishBlock:^(id outputObject, NSError *error) {
            // outputObject 包含所有的响应 http 头部
            NSDictionary* info = (NSDictionary *) outputObject;
        }];
        [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];
    }

    Swift

    for i in 1...10 {
        let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
    
        // 存储桶名称,格式为 BucketName-APPID
        put.bucket = "examplebucket-1250000000";
    
        // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
        put.object = "exampleobject-".appendingFormat("%d", i);
    
        // 需要上传的对象内容
        let dataBody:NSData = "wrwrwrwrwrw".data(using: .utf8)! as NSData;
        put.body = dataBody;
    
        // 监听上传结果
        put.setFinish { (result, error) in
            // 获取上传结果
            if let result = result {
                // 文件的 etag
                let eTag = result.eTag
            } else {
                print(error!);
            }
        }
    
        // 监听上传进度
        put.sendProcessBlock = { (bytesSent, totalBytesSent,
            totalBytesExpectedToSend) in
    
            // bytesSent                   新增字节数
            // totalBytesSent              本次上传的总字节数
            // totalBytesExpectedToSend    本地上传的目标字节数
        };
    
        QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);
    }

    复制对象

    高级接口封装了简单复制、分块复制接口的异步请求,并支持暂停、恢复以及取消复制请求。

    示例代码

    Objective-C

    QCloudCOSXMLCopyObjectRequest* request = [[QCloudCOSXMLCopyObjectRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 文件来源存储桶,需要是公有读或者在当前账号有权限
    request.sourceBucket = @"sourcebucket-1250000000";
    
    // 源文件名称
    request.sourceObject = @"sourceObject";
    
    // 源文件的 APPID
    request.sourceAPPID = @"1250000000";
    
    // 来源的地域
    request.sourceRegion= @"COS_REGION";
    
    [request setFinishBlock:^(QCloudCopyObjectResult* result, NSError* error) {
        // 可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息
    }];
    
    // 注意如果是跨地域复制,这里使用的 transferManager 所在的 region 必须为目标桶所在的 region
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] CopyObject:request];
    
    // 取消copy
    // 若需要取消copy 调用cancel方法
    [request cancel];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let copyRequest =  QCloudCOSXMLCopyObjectRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    copyRequest.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    copyRequest.object = "exampleobject";
    
    // 文件来源存储桶,需要是公有读或者在当前账号有权限
    // 存储桶名称,格式为 BucketName-APPID
    copyRequest.sourceBucket = "sourcebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    copyRequest.sourceObject = "sourceObject";
    
    // 源文件的 APPID
    copyRequest.sourceAPPID = "1250000000";
    
    // 来源的地域
    copyRequest.sourceRegion = "COS_REGION";
    
    copyRequest.setFinish { (copyResult, error) in
        if let copyResult = copyResult {
            // 文件的 etag
            let eTag = copyResult.eTag
        } else {
            print(error!);
        }
    
    }
    // 注意如果是跨地域复制,这里使用的 transferManager 所在的 region 必须为目标桶所在的 region
    QCloudCOSTransferMangerService.defaultCOSTransferManager().copyObject(copyRequest);
    
    // 取消copy
    // 若需要取消copy 调用cancel方法
    copyRequest.cancel();

    说明:

    更多完整示例,请前往 GitHub 查看。

    简单操作

    简单上传对象

    功能说明

    PUT Object 接口可以上传一个对象至指定存储桶中,该操作需要请求者对存储桶有 WRITE 权限。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传高级接口 上传。

    注意:

    1. Key(文件名)不能以/结尾,否则会被识别为文件夹。
    2. 每个主账号(即同一个 APPID),存储桶的 ACL 规则数量最多为1000条,对象 ACL 规则数量不限制。如果您不需要进行对象 ACL 控制,请在上传时不要设置,默认继承存储桶权限。

    示例代码

    Objective-C

    QCloudPutObjectRequest* put = [QCloudPutObjectRequest new];
    
    // 存储桶名称,格式为 BucketName-APPID
    put.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    put.object = @"exampleobject";
    
    // 文件内容,可以传入NSData*或者NSURL*类型的变量
    put.body =  [@"testFileContent" dataUsingEncoding:NSUTF8StringEncoding];
    
    [put setFinishBlock:^(id outputObject, NSError *error) {
        // outputObject 包含所有的响应 http 头部
        NSDictionary* info = (NSDictionary *) outputObject;
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] PutObject:put];

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    Swift

    let putObject = QCloudPutObjectRequest<AnyObject>.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    putObject.bucket = "examplebucket-1250000000";
    // 需要上传的对象内容。可以传入NSData*或者NSURL*类型的变量
    let dataBody:NSData? = "wrwrwrwrwrw".data(using: .utf8) as NSData?;
    putObject.body =  dataBody!;
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    putObject.object = "exampleobject";
    putObject.finishBlock = {(result,error) in
        if let result = result {
            // result 包含响应的 header 信息
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().putObject(putObject);

    说明:

    • 更多完整示例,请前往 GitHub 查看。
    • 上传之后,您可以用同样的 Key 生成文件下载链接,具体使用方法见 生成预签名链接 文档。但注意如果您的文件是私有读权限,那么下载链接只有一定的有效期。

    复制对象(修改属性)

    复制文件到目标路径(PUT Object-Copy)。

    示例代码一: 复制对象时保留对象属性

    Objective-C

    QCloudPutObjectCopyRequest* request = [[QCloudPutObjectCopyRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
    request.metadataDirective = @"Copy";
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    request.accessControlList = @"default";
    
    // 源对象所在的路径
    request.objectCopySource =
    @"sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    
    // 指定源文件的 versionID,只有开启或开启后暂停的存储桶,才会响应此参数
    request.versionID = @"objectVersion1";
    
    [request setFinishBlock:^(QCloudCopyObjectResult * _Nonnull result,
                              NSError * _Nonnull error) {
        // result 返回具体信息
    
    }];
    [[QCloudCOSXMLService defaultCOSXML]  PutObjectCopy:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let putObjectCopy = QCloudPutObjectCopyRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    putObjectCopy.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    putObjectCopy.object = "exampleobject";
    
    // 源对象所在的路径
    putObjectCopy.objectCopySource = "sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
    putObjectCopy.metadataDirective = "Copy";
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    putObjectCopy.accessControlList = "default";
    
    // 指定源文件的 versionID,只有开启或开启后暂停的存储桶,才会响应此参数
    putObjectCopy.versionID = "versionID";
    
    putObjectCopy.setFinish { (result, error) in
        if let result = result {
            let eTag = result.eTag
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().putObjectCopy(putObjectCopy);

    说明:

    更多完整示例,请前往 GitHub 查看。

    示例代码二: 复制对象时替换对象属性

    Objective-C

    QCloudPutObjectCopyRequest* request = [[QCloudPutObjectCopyRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
    request.metadataDirective = @"Replaced";
    
    // 修改元数据
    [request.customHeaders setValue:@"newValue" forKey:@"x-cos-meta-*"];
    
    // 对象存储类型,枚举值请参见 存储类型 文档
    // STANDARD_IA,ARCHIVE。仅当对象不是标准存储(STANDARD)时才会返回该头部
    // 修改存储类型
    [request.customHeaders setValue:@"newValue" forKey:@"x-cos-storage-class"];
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    // 修改acl
    request.accessControlList = @"private";
    
    // 源对象所在的路径
    request.objectCopySource =
        @"sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    
    // 指定源文件的 versionID,只有开启或开启后暂停的存储桶,才会响应此参数
    request.versionID = @"objectVersion1";
    
    [request setFinishBlock:^(QCloudCopyObjectResult * _Nonnull result,
                              NSError * _Nonnull error) {
        // result 返回具体信息
    
    }];
    [[QCloudCOSXMLService defaultCOSXML]  PutObjectCopy:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let request : QCloudPutObjectCopyRequest  = QCloudPutObjectCopyRequest();
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = "exampleobject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
    request.metadataDirective = "Replaced";
    
    // 修改元数据
    request.customHeaders.setValue("newValue", forKey: "x-cos-meta-*");
    
    // 对象存储类型,枚举值请参见 存储类型 文档
    // STANDARD_IA,ARCHIVE。仅当对象不是标准存储(STANDARD)时才会返回该头部
    // 修改存储类型
    request.customHeaders.setValue("newValue", forKey: "x-cos-storage-class");
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    // 修改acl
    request.accessControlList = "源文件acl";
    // 源对象所在的路径
    request.objectCopySource = "sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    
    // 指定源文件的 versionID,只有开启或开启后暂停的存储桶,才会响应此参数
    request.versionID = "versionID";
    
    request.setFinish { (result, error) in
        if let result = result {
            let eTag = result.eTag
        } else {
            print(error!);
        }
    
    }
    QCloudCOSXMLService.defaultCOSXML().putObjectCopy(request);

    说明:

    更多完整示例,请前往 GitHub 查看。

    示例代码三: 修改对象元数据

    Objective-C

    QCloudPutObjectCopyRequest* request = [[QCloudPutObjectCopyRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
    request.metadataDirective = @"Replaced";
    
    // 自定义对象header
    [request.customHeaders setValue:@"newValue" forKey:@"x-cos-meta-*"];
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    request.accessControlList = @"default";
    // 源对象所在的路径
    request.objectCopySource =
        @"examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject";
    
    [request setFinishBlock:^(QCloudCopyObjectResult * _Nonnull result,
                              NSError * _Nonnull error) {
        // result 返回具体信息
    
    }];
    [[QCloudCOSXMLService defaultCOSXML]  PutObjectCopy:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let request : QCloudPutObjectCopyRequest = QCloudPutObjectCopyRequest();
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = "exampleobject";
    
    // 是否拷贝元数据,枚举值:Copy,Replaced,默认值 Copy。
    // 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制
    // 假如标记为 Replaced,按 Header 信息修改元数据。当目标路径和原路径一致
    // 即用户试图修改元数据时,必须为 Replaced
    request.metadataDirective = "Replaced";
    
    // 自定义对象header
    request.customHeaders.setValue("newValue", forKey: "x-cos-meta-*")
    
    // 定义 Object 的 ACL 属性,有效值:private,public-read,default。
    // 默认值:default(继承 Bucket 权限)。
    // 注意:当前访问策略条目限制为1000条,如果您无需进行 Object ACL 控制,请填 default
    // 或者此项不进行设置,默认继承 Bucket 权限。
    request.accessControlList = "default";
    
    // 源对象所在的路径
    request.objectCopySource =
        "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject";
    
    request.setFinish { (result, error) in
        if let result = result {
            // 生成的新文件的 etag
            let eTag = result.eTag
        } else {
            print(error!);
        }
    }
    
    QCloudCOSXMLService.defaultCOSXML().putObjectCopy(request);

    说明:

    更多完整示例,请前往 GitHub 查看。

    示例代码四: 修改对象存储类型

    Objective-C

    QCloudPutObjectCopyRequest* request = [[QCloudPutObjectCopyRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 对象存储类型,枚举值请参见 存储类型 文档
    // STANDARD_IA,ARCHIVE。仅当对象不是标准存储(STANDARD)时才会返回该头部
    [request.customHeaders setValue:@"ARCHIVE" forKey:@"x-cos-storage-class"];
    
    // 源对象所在的路径
    request.objectCopySource =
        @"examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject";
    
    // 指定源文件的 versionID,只有开启或开启后暂停的存储桶,才会响应此参数
    request.versionID = @"";
    
    [request setFinishBlock:^(QCloudCopyObjectResult * _Nonnull result,
                              NSError * _Nonnull error) {
        // result 返回具体信息
    
    }];
    [[QCloudCOSXMLService defaultCOSXML]  PutObjectCopy:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let request : QCloudPutObjectCopyRequest = QCloudPutObjectCopyRequest();
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = "exampleobject";
    
    // 对象存储类型,枚举值请参见 存储类型 文档
    // STANDARD_IA,ARCHIVE。仅当对象不是标准存储(STANDARD)时才会返回该头部
    request.customHeaders.setValue("newValue", forKey: "x-cos-storage-class");
    // 源对象所在的路径
    request.objectCopySource =
        "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject";
    
    request.setFinish { (result, error) in
        if let result = result {
            // 生成的新文件的 etag
            let eTag = result.eTag
        } else {
            print(error!);
        }
    }
    
    QCloudCOSXMLService.defaultCOSXML().putObjectCopy(request);

    说明:

    更多完整示例,请前往 GitHub 查看。

    分块操作

    这里说明下分块上传的流程。

    分块上传与复制的流程

    1. 初始化分块上传(Initiate Multipart Upload),得到 UploadId
    2. 使用 UploadId 上传分块(Upload Part),或者复制分块(Upload Part Copy)
    3. 完成分块上传(Complete Multipart Upload)

    分块继续上传与复制的流程

    1. 如果没有记录 UploadId,查询分块上传任务(List Multipart Uploads),得到对应文件的 UploadId
    2. 使用 UploadId 列出已上传的分块(List Parts)
    3. 使用 UploadId 上传剩余的分块(Upload Part),或者复制剩余的分块(Upload Part Copy)
    4. 完成分块上传(Complete Multipart Upload)

    终止分块上传与复制的流程

    1. 如果没有记录 UploadId,查询分块上传任务(List Multipart Uploads),得到对应文件的 UploadId
    2. 终止分块上传并删除已上传分块(Abort Multipart Upload)

    查询分块上传

    功能说明

    查询指定存储桶中正在进行的分块上传(List Multipart Uploads)。

    示例代码

    Objective-C

    QCloudListBucketMultipartUploadsRequest* uploads = [QCloudListBucketMultipartUploadsRequest new];
    
    // 存储桶名称,格式为 BucketName-APPID
    uploads.bucket = @"examplebucket-1250000000";
    
    // 设置最大返回的 multipart 数量,合法取值从 1 到 1000
    uploads.maxUploads = 100;
    
    [uploads setFinishBlock:^(QCloudListMultipartUploadsResult* result,
                              NSError *error) {
        // 可以从 result 中返回分块信息
        // 进行中的分块上传对象
        NSArray<QCloudListMultipartUploadContent*> *uploads = result.uploads;
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] ListBucketMultipartUploads:uploads];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let listParts = QCloudListBucketMultipartUploadsRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    listParts.bucket = "examplebucket-1250000000";
    
    // 设置最大返回的 multipart 数量,合法取值从 1 到 1000
    listParts.maxUploads = 100;
    
    listParts.setFinish { (result, error) in
        if let result = result {
            // 未完成的所有分块上传任务
            let uploads = result.uploads;
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().listBucketMultipartUploads(listParts);

    说明:

    更多完整示例,请前往 GitHub 查看。

    初始化分块上传

    功能说明

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

    示例代码

    Objective-C

    QCloudInitiateMultipartUploadRequest* initRequest = [QCloudInitiateMultipartUploadRequest new];
    
    // 存储桶名称,格式为 BucketName-APPID
    initRequest.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    initRequest.object = @"exampleobject";
    
    // 将作为对象的元数据返回
    initRequest.cacheControl = @"cacheControl";
    
    initRequest.contentDisposition = @"contentDisposition";
    
    // 定义 Object 的 ACL 属性。有效值:private,public-read-write,public-read;默认值:private
    initRequest.accessControlList = @"public";
    
    // 赋予被授权者读的权限。
    initRequest.grantRead = @"grantRead";
    
    // 赋予被授权者写的权限
    initRequest.grantWrite = @"grantWrite";
    
    // 赋予被授权者读写权限。 grantFullControl == grantWrite + grantRead
    initRequest.grantFullControl = @"grantFullControl";
    
    [initRequest setFinishBlock:^(QCloudInitiateMultipartUploadResult* outputObject,
                                  NSError *error) {
        // 获取分块上传的 uploadId,后续的上传都需要这个 ID,请保存以备后续使用
        self->uploadId = outputObject.uploadId;
    
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] InitiateMultipartUpload:initRequest];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let initRequest = QCloudInitiateMultipartUploadRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    initRequest.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    initRequest.object = "exampleobject";
    
    initRequest.setFinish { (result, error) in
        if let result = result {
            // 获取分块上传的 uploadId,后续的上传都需要这个 ID,请保存以备后续使用
            self.uploadId = result.uploadId;
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().initiateMultipartUpload(initRequest);

    说明:

    更多完整示例,请前往 GitHub 查看。

    上传分块

    分块上传对象(Upload Part)。

    示例代码

    Objective-C

    QCloudUploadPartRequest* request = [QCloudUploadPartRequest new];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 块编号
    request.partNumber = 1;
    
    // 标识本次分块上传的 ID;使用 Initiate Multipart Upload 接口初始化分块上传时会得到一个 uploadId
    request.uploadId = uploadId;
    
    // 上传的数据:支持 NSData*,NSURL(本地 URL) 和 QCloudFileOffsetBody * 三种类型
    request.body = [@"testFileContent" dataUsingEncoding:NSUTF8StringEncoding];
    
    [request setSendProcessBlock:^(int64_t bytesSent,
                                   int64_t totalBytesSent,
                                   int64_t totalBytesExpectedToSend) {
        // 上传进度信息
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    }];
    [request setFinishBlock:^(QCloudUploadPartResult* outputObject, NSError *error) {
        QCloudMultipartInfo *part = [QCloudMultipartInfo new];
        // 获取所上传分块的 etag
        part.eTag = outputObject.eTag;
        part.partNumber = @"1";
        // 保存起来用于最好完成上传时使用
        self.parts = @[part];
    
    }];
    
    [[QCloudCOSXMLService defaultCOSXML]  UploadPart:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let uploadPart = QCloudUploadPartRequest<AnyObject>.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    uploadPart.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    uploadPart.object = "exampleobject";
    uploadPart.partNumber = 1;
    
    // 标识本次分块上传的 ID
    if let uploadId = self.uploadId {
        uploadPart.uploadId = uploadId;
    }
    
    // 示例文件内容
    let dataBody:NSData? = "wrwrwrwrwrwwrwrwrwrwrwwwrwrw"
        .data(using: .utf8) as NSData?;
    
    uploadPart.body = dataBody!;
    uploadPart.setFinish { (result, error) in
        if let result = result {
            let mutipartInfo = QCloudMultipartInfo.init();
            // 获取分块的 etag
            mutipartInfo.eTag = result.eTag;
            mutipartInfo.partNumber = "1";
            // 保存起来用于最后完成上传时使用
            self.parts = [mutipartInfo];
        } else {
            print(error!);
        }
    }
    uploadPart.sendProcessBlock = {(bytesSent,totalBytesSent,
                                    totalBytesExpectedToSend) in
        // 上传进度信息
        // bytesSent                   新增字节数
        // totalBytesSent              本次上传的总字节数
        // totalBytesExpectedToSend    本地上传的目标字节数
    
    }
    QCloudCOSXMLService.defaultCOSXML().uploadPart(uploadPart);

    说明:

    更多完整示例,请前往 GitHub 查看。

    复制分块

    功能说明

    将其他对象复制为一个分块 (Upload Part-Copy)。

    示例代码

    Objective-C

    QCloudUploadPartCopyRequest* request = [[QCloudUploadPartCopyRequest alloc] init];
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 源文件 URL 路径,可以通过 versionid 子资源指定历史版本
    request.source = @"sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    
    // 在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID)
    request.uploadID = uploadId;
    
    // 标志当前分块的序号
    request.partNumber = 1;
    
    [request setFinishBlock:^(QCloudCopyObjectResult* result, NSError* error) {
        QCloudMultipartInfo *part = [QCloudMultipartInfo new];
    
        // 获取所复制分块的 etag
        part.eTag = result.eTag;
        part.partNumber = @"1";
        // 保存起来用于最后完成上传时使用
        self.parts=@[part];
    
    }];
    
    [[QCloudCOSXMLService defaultCOSXML]UploadPartCopy:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let req = QCloudUploadPartCopyRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    req.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    req.object = "exampleobject";
    
    // 源文件 URL 路径,可以通过 versionid 子资源指定历史版本
    req.source = "sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject";
    // 在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID)
    if let uploadId = self.uploadId {
        req.uploadID = uploadId;
    }
    
    // 标志当前分块的序号
    req.partNumber = 1;
    req.setFinish { (result, error) in
        if let result = result {
            let mutipartInfo = QCloudMultipartInfo.init();
            // 获取所复制分块的 etag
            mutipartInfo.eTag = result.eTag;
            mutipartInfo.partNumber = "1";
            // 保存起来用于最后完成复制时使用
            self.parts = [mutipartInfo];
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().uploadPartCopy(req);

    说明:

    更多完整示例,请前往 GitHub 查看。

    查询已上传的分块

    功能说明

    查询特定分块上传操作中的已上传的块(List Parts)。

    示例代码

    Objective-C

    QCloudListMultipartRequest* request = [QCloudListMultipartRequest new];
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    request.object = @"exampleobject";
    
    // 存储桶名称,格式为 BucketName-APPID
    request.bucket = @"examplebucket-1250000000";
    
    // 在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID)
    request.uploadId = uploadId;
    
    [request setFinishBlock:^(QCloudListPartsResult * _Nonnull result,
                              NSError * _Nonnull error) {
    
        // 从 result 中获取已上传分块信息
        // 用来表示每一个块的信息
        NSArray<QCloudMultipartUploadPart*> *parts = result.parts;
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] ListMultipart:request];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let req = QCloudListMultipartRequest.init();
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    req.object = "exampleobject";
    
    // 存储桶名称,格式为 BucketName-APPID
    req.bucket = "examplebucket-1250000000";
    
    // 在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID)
    if let uploadId = self.uploadId {
        req.uploadId = uploadId;
    }
    req.setFinish { (result, error) in
        if let result = result {
            // 所有已完成的分片
            let parts = result.parts
        } else {
            print(error!);
        }
    }
    
    QCloudCOSXMLService.defaultCOSXML().listMultipart(req);

    说明:

    更多完整示例,请前往 GitHub 查看。

    完成分块上传

    功能说明

    完成整个文件的分块上传(Complete Multipart Upload)。

    示例代码

    Objective-C
    //: # (.cssg-snippet-complete-multi-upload)

    QCloudCompleteMultipartUploadRequest *completeRequst = [QCloudCompleteMultipartUploadRequest new];
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    completeRequst.object = @"exampleobject";
    
    // 存储桶名称,格式为 BucketName-APPID
    completeRequst.bucket = @"examplebucket-1250000000";
    
    // 本次要查询的分块上传的 uploadId,可从初始化分块上传的请求结果 QCloudInitiateMultipartUploadResult 中得到
    completeRequst.uploadId = uploadId;
    
    // 已上传分块的信息
    QCloudCompleteMultipartUploadInfo *partInfo = [QCloudCompleteMultipartUploadInfo new];
    NSMutableArray * parts = [self.parts mutableCopy];
    
    // 对已上传的块进行排序
    [parts sortUsingComparator:^NSComparisonResult(QCloudMultipartInfo*  _Nonnull obj1,
                                                   QCloudMultipartInfo*  _Nonnull obj2) {
        int a = obj1.partNumber.intValue;
        int b = obj2.partNumber.intValue;
    
        if (a < b) {
            return NSOrderedAscending;
        } else {
            return NSOrderedDescending;
        }
    }];
    partInfo.parts = [parts copy];
    completeRequst.parts = partInfo;
    
    [completeRequst setFinishBlock:^(QCloudUploadObjectResult * _Nonnull result,
                                     NSError * _Nonnull error) {
        // 从 result 中获取上传结果
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] CompleteMultipartUpload:completeRequst];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift
    //: # (.cssg-snippet-complete-multi-upload)

    let  complete = QCloudCompleteMultipartUploadRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    complete.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    complete.object = "exampleobject";
    
    // 本次要查询的分块上传的 uploadId,可从初始化分块上传的请求结果
    // QCloudInitiateMultipartUploadResult 中得到
    complete.uploadId = "exampleUploadId";
    if let uploadId = self.uploadId {
        complete.uploadId = uploadId;
    }
    
    // 已上传分块的信息
    let completeInfo = QCloudCompleteMultipartUploadInfo.init();
    if self.parts == nil {
        print("没有要完成的分块");
        return;
    }
    if self.parts != nil {
        completeInfo.parts = self.parts ?? [];
    }
    
    complete.parts = completeInfo;
    complete.setFinish { (result, error) in
        if let result = result {
            // 文件的 eTag
            let eTag = result.eTag
            // 不带签名的文件链接
            let location = result.location
        } else {
            print(error!);
        }
    }
    QCloudCOSXMLService.defaultCOSXML().completeMultipartUpload(complete);

    说明:

    更多完整示例,请前往 GitHub 查看。

    终止分块上传

    功能说明

    终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。

    示例代码

    Objective-C

    QCloudAbortMultipfartUploadRequest *abortRequest = [QCloudAbortMultipfartUploadRequest new];
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    abortRequest.object = @"exampleobject";
    
    // 存储桶名称,格式为 BucketName-APPID
    abortRequest.bucket = @"examplebucket-1250000000";
    
    // 本次要终止的分块上传的 uploadId
    // 可从初始化分块上传的请求结果 QCloudInitiateMultipartUploadResult 中得到
    abortRequest.uploadId = @"exampleUploadId";
    
    [abortRequest setFinishBlock:^(id outputObject, NSError *error) {
        // 可以从 outputObject 中获取 response 中 etag 或者自定义头部等信息
        NSDictionary * result = (NSDictionary *)outputObject;
    }];
    
    [[QCloudCOSXMLService defaultCOSXML]AbortMultipfartUpload:abortRequest];

    说明:

    更多完整示例,请前往 GitHub 查看。

    Swift

    let abort = QCloudAbortMultipfartUploadRequest.init();
    
    // 存储桶名称,格式为 BucketName-APPID
    abort.bucket = "examplebucket-1250000000";
    
    // 对象键,是对象在 COS 上的完整路径,如果带目录的话,格式为 "dir1/object1"
    abort.object = "exampleobject";
    
    // 本次要查询的分块上传的 uploadId,可从初始化分块上传的请求结果
    // QCloudInitiateMultipartUploadResult 中得到
    abort.uploadId = self.uploadId!;
    
    abort.finishBlock = {(result,error)in
        if let result = result {
            // 可以从 result 中获取服务器返回的 header 信息
        } else {
            print(error!)
        }
    }
    QCloudCOSXMLService.defaultCOSXML().abortMultipfartUpload(abort);

    说明:

    更多完整示例,请前往 GitHub 查看。

    Was this page helpful?

    本页内容是否解决了您的问题?

    • 完全没帮助
    • 文档较差
    • 文档一般
    • 文档不错
    • 文档很好
    反馈
    帮助