Bucket Operations

Last updated: 2020-07-03 11:22:06

    Introduction

    This document provides an overview of APIs and SDK code samples related to basic operations on buckets and bucket access control list (ACL).

    • We assume you have completed SDK download, installation, and initialization as described in Getting Started.
      We recommend you use Control+F to find the desired API, view our API description, copy the examples and run them in your project.

    If you need more features, or do not understand what the returned parameters mean, we recommend you view the comments in the code using three finger drag, Force-touch, or hovering over the variable and pressing Control+Command+D.

    Basic Operations

    API Operation Description
    GET Service Querying bucket list Queries the list of all buckets under a specified account
    PUT Bucket Creating a bucket Creates a bucket under the specified account
    HEAD Bucket Checking a bucket and its permission Checks whether a bucket exists and you have permission to access it
    DELETE Bucket Deleting a bucket Deletes an empty bucket under the specified account

    ACL

    API Operation Description
    PUT Bucket acl Setting bucket ACL Sets the ACL for a specified bucket
    GET Bucket acl Querying bucket ACL Queries the ACL of a bucket

    Basic Operations

    Querying the bucket list

    Feature

    This API is used to query the list of all buckets under the specified account.

    Returned Result

    Parameters of returned result QCloudListAllMyBucketsResult

    Parameter Name Description Type
    owner Bucket owner information QCloudOwner *
    buckets All bucket information NSArray<QCloudBucket*>*

    QCloudOwner parameter description

    Parameter Name Description Type
    - - - DisplayName Part owner name String
    ID ID of the bucket owner string

    QCloudBucket parameter description

    Parameter Name Description Type
    Name Bucket name string
    x-cos-bucket-region Bucket region such as ap-beijing, ap-hongkong, and eu-frankfurt. For the enumerated values, see Regions and Access Domain Names Enum
    CreationDate Time when the bucket was created, in ISO8601 format, such as 2016-11-09T08:46:32.000Z string

    Request Example

    Objective-C code sample:

    QCloudGetServiceRequest* request = [[QCloudGetServiceRequest alloc] init];
    [request setFinishBlock:^(QCloudListAllMyBucketsResult* result, NSError* error) {
        // Get the returned information from result
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObject:request];

    Swift code sample:

    let getServiceReq = QCloudGetServiceRequest.init();
    getServiceReq.setFinish{(result,error) in
        if result == nil {
            print(error!);
        } else {
            // Get the returned information from result
            print(result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().getService(getServiceReq);

    Creating a bucket

    Feature

    This API (PUT Bucket) is used to create a bucket under a specified account.

    Method Prototype

    Before using COS, you need to create a bucket under the specific account for use and management of objects, and define the region of the bucket. The creator of the bucket is the owner of the bucket by default. The bucket access permission is Private Read/Write by default if not otherwise specified upon creation. Specific steps are as follows:

    1. Instantiate QCloudPutBucketRequest and enter the required parameters.
    2. Call the PutBucket method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from outputObject in finishBlock of callback.

    Parameter Description

    QCloudPutBucketRequest parameters

    Parameter Name Description Type Required
    bucket Name of the bucket to be created. For naming rules, see Naming Conventions NSString* Yes
    accessControlList Defines the ACL attribute of a bucket. Valid values: private, public-read-write, public-read; Default: private NSString * No
    GrantRead Grants the grantee Read access in the format of id="[OwnerUin]" String No
    GrantWrite Grants the grantee Write access in the format of id="[OwnerUin]" String No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No

    Request Example

    Objective-C code sample:

    QCloudPutBucketRequest* request = [QCloudPutBucketRequest new];
    request.bucket = @"examplebucket-1250000000"; //additional actions after finishing
    [request setFinishBlock:^(id outputObject, NSError* error) {
        // You can get the header information returned by the server from outputObject
    }];
    [[QCloudCOSXMLService defaultCOSXML] PutBucketVersioning:request];

    Swift code sample:

    let putBucketReq = QCloudPutBucketRequest.init();
    putBucketReq.bucket = "examplebucket-1250000000";
    putBucketReq.finishBlock = {(result,error) in
        if error != nil {
            print(error!);
        } else {
            print(result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().putBucket(putBucketReq);

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.
    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    • For SDK-defined custom error codes, they are all 5-digit positive numbers, such as 10000, 20000, etc. For solutions regarding these error codes, refer to SDK Error Code.

    Retrieving information on a bucket and its permission

    Feature

    This API is used to verify whether a bucket exists and whether you have the permission to access it. The permission requirements for HEAD Bucket are the same as those for GET Bucket. 200 is returned if the bucket exists; 403 is returned if you do not have access to the bucket; 404 is returned if the bucket does not exist.

    QCloudHeadBucketRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Samples

    Objective-C code sample:

    QCloudHeadBucketRequest* request = [QCloudHeadBucketRequest new];
    request.bucket = @"examplebucket-1250000000";
    [request setFinishBlock:^(id outputObject, NSError* error) {
        // You can get the header information returned by the server from outputObject
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObject:request];

    Swift code sample:

    let headBucketReq = QCloudHeadBucketRequest.init();
    headBucketReq.bucket = "examplebucket-1250000000";
    headBucketReq.finishBlock = {(result,error) in
        if error != nil{
            print(error!);
        }else{
            print( result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().headBucket(headBucketReq);

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    • For SDK-defined custom error codes, they are all 5-digit positive numbers, such as 10000, 20000, etc. For solutions regarding these error codes, refer to SDK Error Code.

    Deleting a bucket

    Feature

    This API is used to delete the empty bucket under the specified account.

    Method Prototype

    The steps to delete a bucket in COS iOS SDK are as follows:

    1. Instantiate QCloudDeleteBucketCORSRequest and enter the required parameters.
    2. Call the GetBucket method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from outputObject in finishBlock of callback.

    Parameter Description

    QCloudDeleteBucketCORSRequest parameters

    Parameter Name Description Type Required
    bucket Name of the bucket to be deleted, can be viewed in COS Console, naming format is BucketName-APPID
    such as examplebucket-1250000000. Note: bucket is required to be empty before deletion
    NSString* Yes

    Request Example

    Objective-C code sample:

    QCloudDeleteBucketRequest* request = [[QCloudDeleteBucketRequest alloc ] init];
    String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
    [request setFinishBlock:^(id outputObject, NSError* error) {
        // You can get the header information returned by the server from outputObject
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetObject:request];

    Swift code sample:

    let deleteBucketReq = QCloudDeleteBucketRequest.init();
    deleteBucketReq.bucket = "examplebucket-1250000000";
    deleteBucketReq.finishBlock = {(result,error) in
        if error != nil{
            print(error!);
        }else{
            print(result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().deleteBucket(deleteBucketReq);

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    • For SDK-defined custom error codes, they are all 5-digit positive numbers, such as 10000, 20000, etc. For solutions regarding these error codes, refer to SDK Error Code.

    ACL

    Setting bucket ACL

    Feature

    This API (PUT Bucket acl) is used to set the access control list (ACL) for a specified bucket.

    Method Prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudPutBucketACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudPutBucketACLRequest, enter the bucket to be set, and then enter corresponding parameters according to the permission type of the bucket.
    2. Call the PutBucketACL method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain the setting result (successful or failed) from finishBlock of callback, and perform some additional operations if the setting is successful.

    QCloudPutBucketACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes
    accessControlList Defines the ACL attribute of a bucket. Valid values: private, public-read-write, public-read; Default: private NSString * No
    GrantRead Grants the grantee Read access in the format of id="[OwnerUin]" String No
    GrantWrite Grants the grantee Write access in the format of id="[OwnerUin]" String No
    GrantFullControl Grants the grantee full permission in the format of id="[OwnerUin]" String No

    Samples

    Objective-C code sample:

    QCloudPutBucketACLRequest* putACL = [QCloudPutBucketACLRequest new];
    NSString* appID = @"1131975903";// Grant a new account ID
    NSString *ownerIdentifier = [NSString stringWithFormat:@"qcs::cam::uin/%@:uin/%@", appID,
        ### APPID
    NSString *grantString = [NSString stringWithFormat:@"id=\"%@\"",ownerIdentifier];
    putACL.grantFullControl = grantString;
    String bucket = "examplebucket-1250000000";
    [request setFinishBlock:^(id outputObject, NSError* error) {
        // You can get the header information returned by the server from outputObject
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] PutBucketACL:putACL];

    Swift code sample:

    let putBucketACLReq = QCloudPutBucketACLRequest.init();
    putBucketACLReq.bucket = "examplebucket-1250000000";
    let appTD = "1131975903";// Grant a new account ID
    let ownerIdentifier = "qcs::cam::uin/\(appTD):uin/\(appTD)";
    let grantString = "id=\"\(ownerIdentifier)\"";
    putBucketACLReq.grantWrite = grantString;
    putBucketACLReq.finishBlock = {(result,error) in
        if error != nil{
            print(error!);
        }else{
            print(result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().putBucketACL(putBucketACLReq);

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    • For SDK-defined custom error codes, they are all 5-digit positive numbers, such as 10000, 20000, etc. For solutions regarding these error codes, refer to SDK Error Code.

    Querying bucket ACL

    Feature

    This API (GET Bucket acl) is used to query the access control list (ACL) of a bucket.

    Method Prototype

    The header file QCloudCOSXML/QCloudCOSXML.h needs to be imported before bucket operations. Before that, you need to complete the initialization described in Getting Started by creating a QCloudGetBucketACLRequest instance and enter some additional restrictions as needed to get the approved content. Specific steps are as follows:

    1. Instantiate QCloudGetBucketACLRequest and enter the bucket whose ACL is to be obtained.
    2. Call the GetBucketACL method in the QCloudCOSXMLService object to initiate a request.
    3. Obtain specific content from QCloudACLPolicy in finishBlock of callback.

    QCloudGetBucketACLRequest parameters

    Parameter Name Description Type Required
    bucket Bucket name, which can be found in the COS V5 Console, with a format of <bucketName>-<APPID>, such as testBucket-1253653367. NSString * Yes

    Returned Result

    Parameters of returned result QCloudACLPolicy

    Parameter Name Description Type
    displayName Bucket owner information NSString *
    - - ID Bucket owner ID in the format of qcs::cam::uin/<OwnerUin>:uin/<SubUin>.
    For root accounts, <OwnerUin> and <SubUin> have the same value
    String

    QCloudACLOwner parameters

    Parameter Name Description Type
    owner Bucket owner information QCloudACLOwner *
    accessControlList Information of the authorized user and permissions QCloudAccessControlList *

    QCloudAccessControlList parameters

    Parameter Name Description Type
    ACLGrants An array to store information about grantees NSArray<QCloudACLGrant*>*

    Samples

    Objective-C code sample:

    QCloudGetBucketACLRequest* getBucketACl = [QCloudGetBucketACLRequest new];
    getBucketACl.bucket = @"examplebucket-1250000000";
    [getBucketACl setFinishBlock:^(QCloudACLPolicy * _Nonnull result, NSError * _Nonnull error) {
        QCloudACLPolicy contains Bucket ACL information.
    }];
    
    [[QCloudCOSXMLService defaultCOSXML] GetBucketACL:getBucketACl];

    Swift code sample:

    let getBucketACLReq = QCloudGetBucketACLRequest.init();
    getBucketACLReq.bucket = "examplebucket-1250000000";
    getBucketACLReq.setFinish { (result, error) in
        if error != nil{
            print(error!);
        }else{
            print(result!);
        }}
    QCloudCOSXMLService.defaultCOSXML().getBucketACL(getBucketACLReq)

    Error codes

    When the SDK request fails, the error returned is not empty and includes the error code, error description, and other necessary debugging information to help developers quickly solve the problem.

    Error codes (encapsulated in the returned error) include those returned by the device due to network problems and those returned by COS.

    Error codes generated by the device due to network problems are negative four digits, for example -1001. These error codes are defined by Apple. For more information, see the definitions in the header file NSURLError.h or Apple's official documentation.
    Error codes returned by COS are based on HTTP status codes, such as 404 and 503. For solutions to these error codes, see Error Codes in COS official documentation.

    • For SDK-defined custom error codes, they are all 5-digit positive numbers, such as 10000, 20000, etc. For solutions regarding these error codes, refer to SDK Error Code.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help