Bucket management

Create Bucket

• Basic workflow

  1. Instantiate the BOSClient class.
  2. To execute the BOSClient.putBucket() method, you need to specify the bucket name.

• Example code

  Swift Copy

  1BCETask* task = [client putBucket:@"<bucketname>"]; //Create a new bucket and specify the bucket name

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4// Initialize
  5BCECredentials* credentials = [[BCECredentials alloc] init];
  6credentials.accessKey = @"<access key>";
  7credentials.secretKey = @"<secret key>";
  8BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9configuration.credentials = credentials;
  10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11BCETask* task = [client putBucket:@"<bucketName>"];
  12task.then(^(BCEOutput* output) { // The task can be executed asynchronously.
  13    if (output.response) {
  14// Task executed successfully.
  15    }
  16    if (output.error) {
  17// Task execution failed.
  18    }
  19    if (output.progress) {
  20// Task execution progress.
  21    }
  22});
  23[task waitUtilFinished]; // You can wait synchronously until the task is finished.
  24}  

  Plain Text Copy

  1> **Note:** Since bucket names are globally unique across all regions, ensure the BucketName does not conflict with any existing BucketName in other regions.

View bucket list

• Basic workflow

  1. Instantiate the BOSClient class.
  2. Using the BOSClient's listBuckets method returns an instance of the BOSListBucketResponse class.
  3. Instances of the BOSListBucketResponse class can retrieve bucket and owner information.

• Example code

  The following code can list all buckets of a user:

  Swift Copy

  1__block BOSListBucketResponse* response = nil;
  2BCETask* task = [client listBuckets];
  3task.then(^(BCEOutput* output) {
  4    if (output.response) {
  5      response = (BOSListBucketResponse*)output.response;
  6    }
  7    if (output.error) {
  8    }
  9});
  10[task waitUtilFinished];

  The following code can list the bucket's owner:

  Swift Copy

  1BOSBucketOwner* owner = response.owner;

  The following code can list the mucket's metadata:

  Swift Copy

  1NSArray<BOSBucketSummary*>* buckets = response.buckets;
  2for (BOSBucketSummary* bucket in buckets) {
  3    NSLog(@"bucket name: %@", bucket.name);
  4    NSLog(@"bucket location: %@", bucket.location);
  5    NSLog(@"bucket create date: %@", bucket.createDate);
  6}

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4// Initialize
  5    BCECredentials* credentials = [[BCECredentials alloc] init];
  6    credentials.accessKey = @"<access key>";
  7    credentials.secretKey = @"<secret key>";
  8    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9    configuration.credentials = credentials;
  10    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11// List buckets
  12    __block BOSListBucketResponse* response = nil;
  13    BCETask* task = [client listBuckets];
  14    task.then(^(BCEOutput* output) {
  15        if (output.response) {
  16            response = (BOSListBucketResponse*)output.response;
  17        }
  18        if (output.error) {
  19        }
  20    });
  21    [task waitUtilFinished];
  22// Get owner
  23    BOSBucketOwner* owner = response.owner;
  24    NSLog(@"the buckets owner is %@", owner.ownerID);
  25// Get bucket information
  26    NSArray<BOSBucketSummary*>* buckets = response.buckets;
  27    for (BOSBucketSummary* bucket in buckets) {
  28        NSLog(@"bucket name: %@", bucket.name);
  29        NSLog(@"bucket location: %@", bucket.location);
  30        NSLog(@"bucket create date: %@", bucket.createDate);
  31    }
  32}

Determine whether the bucket exists and whether there is permission to access it

• Basic workflow

  1. Create an instance of the BOSClient class.
  2. Execute the BOSClient headBucket method;
  3. If no errors occur in the request, the bucket exists, and the requester has permission to access it.

• Example code

  Swift Copy

  1__block BOSHeadBucketResponse* response = nil;
  2BCETask* task = [client headBucket:@"<bucketname>"];
  3 task.then(^(BCEOutput* output) {
  4    if (output.response) {
  5        response = (BOSHeadBucketResponse*)output.response;
  6        NSLog(@"head bucket success!");
  7    }
  8  if (output.error) {
  9      NSLog(@"Bucket not exist or no permission!");
  10  }
  11});
  12[task waitUtilFinished];

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4 // Initialize
  5BCECredentials* credentials = [[BCECredentials alloc] init];
  6credentials.accessKey = @"<access key>";
  7credentials.secretKey = @"<secret key>";
  8BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9configuration.credentials = credentials;
  10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11__block BOSHeadBucketResponse* response = nil;
  12BCETask* task = [client headBucket:@"<bucketname>"];
  13task.then(^(BCEOutput* output) {
  14    if (output.response) {
  15        response = (BOSHeadBucketResponse*)output.response;
  16        NSLog(@"head bucket success!");
  17    }
  18    if (output.error) {
  19        NSLog(@"Bucket not exist or no permission!");
  20    }
  21});
  22[task waitUtilFinished];
  23}

Delete bucket

• Basic workflow

  1. Create an instance of the BOSClient class.
  2. Execute the BOSClient deleteBucket method;
  3. An error occurs if the deletion process fails.

• Example code

  Swift Copy

  1__block BOSDeleteBucketResponse* response = nil;
  2BCETask* task = [client deleteBucket:@"<bucketname>"];
  3task.then(^(BCEOutput* output) {
  4  if (output.response) {
  5      response = (BOSDeleteBucketResponse*)output.response;
  6      NSLog(@"delete bucket success!");
  7  }
  8  if (output.error) {
  9      NSLog(@"delete bucket failure");
  10  }
  11});
  12[task waitUtilFinished];

  Plain Text Copy

  1> **Note:** A bucket cannot be deleted if it is not empty (i.e., it contains objects or unfinished multipart uploads). The bucket must be emptied before successful deletion.

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4 // Initialize
  5BCECredentials* credentials = [[BCECredentials alloc] init];
  6credentials.accessKey = @"<access key>";
  7credentials.secretKey = @"<secret key>";
  8BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9configuration.credentials = credentials;
  10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11__block BOSDeleteBucketResponse* response = nil;
  12BCETask* task = [client deleteBucket:@"<bucketname>"];
  13task.then(^(BCEOutput* output) {
  14    if (output.response) {
  15        response = (BOSDeleteBucketResponse*)output.response;
  16        NSLog(@"delete bucket success!");
  17    }
  18    if (output.error) {
  19        NSLog(@"delete bucket failure");
  20    }
  21});
  22[task waitUtilFinished];
  23}

Bucket permission control

Set bucket access permission

• Basic workflow

  1. Create an instance of the BOSClient class.
  2. Execute the BOSClient putBucketACL method;
  3. An error occurs if the settings cannot be applied.

• Example code

  Swift Copy

  1BOSPutBucketAclRequest* request = [[BOSPutBucketAclRequest alloc] init];
  2request.cannedAcl = BOS_ACL_PUBLIC_READ;
  3request.bucket = @"<bucketname>";
  4__block BOSPutBucketAclResponse* response = nil;
  5BCETask* task = [client putBucketACL:request];
  6task.then(^(BCEOutput* output) {
  7  if (output.response) {
  8      response = (BOSPutBucketAclResponse*)output.response;
  9      NSLog(@"pub bucket acl success!");
  10  }
  11  if (output.error) {
  12      NSLog(@"pub bucket acl failure with %@", output.error);
  13  }
  14});
  15[task waitUtilFinished];

  Plain Text Copy

  1> **Note: **The cannedAcl field can take 3 values: `Private`, `PublicRead`, and `PublicReadWrite`, which correspond to relevant permissions respectively. For specific contents, please refer to BOS API Documentation [Permission Control Using CannedAcl](BOS/API Reference/Access control.md#Permission control by CannedAcl).

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4 // Initialize
  5BCECredentials* credentials = [[BCECredentials alloc] init];
  6credentials.accessKey = @"<access key>";
  7credentials.secretKey = @"<secret key>";
  8BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9configuration.credentials = credentials;
  10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11BOSPutBucketAclRequest* request = [[BOSPutBucketAclRequest alloc] init];
  12request.cannedAcl = BOS_ACL_PUBLIC_READ;
  13request.bucket = @"<bucketname>";
  14__block BOSPutBucketAclResponse* response = nil;
  15BCETask* task = [client putBucketACL:request];
  16task.then(^(BCEOutput* output) {
  17    if (output.response) {
  18        response = (BOSPutBucketAclResponse*)output.response;
  19        NSLog(@"pub bucket acl success!");
  20    }
  21    if (output.error) {
  22        NSLog(@"pub bucket acl failure with %@", output.error);
  23    }
  24});
  25[task waitUtilFinished];
  26}

Set access permissions for a specific user on the bucket

• Basic workflow

  1. Instantiate the BOSClient class.
  2. To use the putBucketAcl method, you must create an instance of BOSPutBucketAclRequest to provide the authorized user information.
  3. An exception is thrown if the settings cannot be applied.

• Example code

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4 // Initialize
  5    BCECredentials* credentials = [[BCECredentials alloc] init];
  6    credentials.accessKey = @"<access key>";
  7        credentials.secretKey = @"<secret key>";
  8    BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9    configuration.credentials = credentials;
  10    BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11    NSArray<NSString*>* grantee = @[
  12                                    @"<grantee1>",
  13                                    @"<grantee2>"
  14                                    ];
  15    NSArray<NSString*>* permission = @[
  16                                        [BOSGrant permissionToString:BOSBucketGranteePermissionRead],
  17                                        [BOSGrant permissionToString:BOSBucketGranteePermissionList],
  18                                        ];
  19    BOSGrant* grant = [[BOSGrant alloc] init];
  20    grant.granteeIDArray = grantee;
  21    grant.permission = permission;
  22    BOSPutBucketAclRequest* request = [[BOSPutBucketAclRequest alloc] init];
  23    request.acl = [[BOSACL alloc] init];
  24    request.acl.grantees = @[grant];
  25    request.bucket = @"<bucketname>";
  26    __block BOSPutBucketAclResponse* response = nil;
  27    BCETask* task = [client putBucketACL:request];
  28    task.then(^(BCEOutput* output) {
  29        if (output.response) {
  30            response = (BOSPutBucketAclResponse*)output.response;
  31            NSLog(@"pub bucket acl success!");
  32        }
  33        if (output.error) {
  34            NSLog(@"pub bucket acl failure with %@", output.error);
  35        }	
  36    });
  37    [task waitUtilFinished];
  38}

  Plain Text Copy

  1> **Attention**: The permission settings in Permission include five values: `READ`, `WRITE`, `LIST`, `GetObject`, and `FULL_CONTROL`, which correspond to relevant permissions respectively. For specific contents, please refer to BOS API Documentation [Permission Control via Uploading ACL Files](BOS/API Reference/Access control.md#Permission control by uploading ACL files).

• Complete example

  Swift Copy

  1#import <BaiduBCEBasic/BaiduBCEBasic.h>
  2#import <BaiduBCEBOS/BaiduBCEBOS.h>
  3void example(void) {
  4 // Initialize
  5BCECredentials* credentials = [[BCECredentials alloc] init];
  6credentials.accessKey = @"<access key>";
  7credentials.secretKey = @"<secret key>";
  8BOSClientConfiguration* configuration = [[BOSClientConfiguration alloc] init];
  9configuration.credentials = credentials;
  10BOSClient* client = [[BOSClient alloc] initWithConfiguration:configuration];
  11    NSArray<NSString*>* grantee = @[
  12    @"<grantee1>",
  13    @"<grantee2>"
  14];
  15NSArray<NSString*>* permission = @[
  16    [BOSGrant permissionToString:BOSBucketGranteePermissionRead],
  17    [BOSGrant permissionToString:BOSBucketGranteePermissionList],
  18];
  19BOSGrant* grant = [[BOSGrant alloc] init];
  20grant.granteeIDArray = grantee;
  21grant.permission = permission;
  22BOSPutBucketAclRequest* request = [[BOSPutBucketAclRequest alloc] init];
  23request.acl = @[grant];
  24request.bucket = @"<bucketname>";
  25__block BOSPutBucketAclResponse* response = nil;
  26BCETask* task = [client putBucketACL:request];
  27task.then(^(BCEOutput* output) {
  28    if (output.response) {
  29        response = (BOSPutBucketAclResponse*)output.response;
  30        NSLog(@"pub bucket acl success!");
  31    }
  32    if (output.error) {
  33        NSLog(@"pub bucket acl failure with %@", output.error);
  34    }
  35});
  36[task waitUtilFinished];
  37}