A bucket is not only a namespace on BOS but also a management entity for advanced functions, such as billing, access control, and logging.

• The bucket name is globally unique in all regions and cannot be modified.

Descriptions:

• At present, Baidu AI Cloud provides multi-region support. See Instruction for Region Selection. At present, it supports three regions, including "North China - Beijing", "South China - Guangzhou", and "East China - Suzhou". Beijing region:http://bj.bcebos.com, Guangzhou region: http://gz.bcebos.com, Suzhou region: http://su.bcebos.com.

• Each object stored in BOS must be included in a bucket.
• A user can create up to 100 buckets, but the number and total size of objects stored in each bucket are not limited, and users do not need to consider the scalability of data.

Bucket Access Control

Set bucket access permission

The following code sets the bucket permission to private:

use BaiduBce\Services\Bos\CannedAcl;
$client->setBucketCannedAcl($bucket, CannedAcl::ACL_PRIVATE);

Three parameters are encapsulated in CannedAcl.php: ACL_PRIVATE, ACL_PUBLIC_READ and ACL_PUBLIC_READ_WRITE, whose corresponding permissions are private, public-read, and public-read-write, respectively. For the specific content of permission, please see Access Control in CannedAcl Mode in the BOS API Documentation.

Set access control of bucket for the specified user

BOS provides the setBucketAcl method to set the access control of buckets for the specified user. You can see the following codes for implementation:

$my_acl = array(
    array(
        'grantee' => array(
             array(
                 'id' => '7f34788d02a64a9c98f85600567d98a7',
             ),
             array(
                 'id' => 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
             ),
         ),
         'permission' => array('FULL_CONTROL'),
    ),
);
$client->setBucketAcl($bucket, $my_acl);

Notes:

1. The access control in permission contains three values:READ,WRITEandFULL_CONTROL, which correspond to relevant permissions, respectively. For the specific content, please see Access Control by Uploading ACL File in BOS API Documentation.
2. When more than two (including two) grantees are set, please see the format of the example above. If the arrays are merged, an error occurs.

Set more bucket access permissions

1. Set the hotlink protection by setting the referer whitelist.

$my_acl = array(
    array(
        'grantee' => array(
            array(
                'id' => '7f34788d02a64a9c98f85600567d98a7',
            ),
        ),
        'permission' => array('FULL_CONTROL'),
        'condition' => array(
            'referer' => array(
                'stringLike' => array('http://www.abc.com/*'),
                'stringEquals' => array('http://www.abc.com'),
            ),
        ),
    ),
);
$client->setBucketAcl($bucket, $my_acl);

2. Restrict client IP access, but allow partial client IP access only.

$my_acl = array(
    array(
         'grantee' => array(
              array(
                  'id' => '7f34788d02a64a9c98f85600567d98a7',
              ),
         ),
         'permission' => array('FULL_CONTROL'),
         'condition' => array(
            'ipAddress' => array("192.168.0.0/16"),
         ),
    ),
);
$client->setBucketAcl($bucket, $my_acl);

Set STS temporary token permission

For the temporary access identity created through STS, the administrator can also set the special access control. For the introduction to STS and how to set the temporary access control, please see Temporary Access Control.

To set the STS temporary token permission through BOS PHP SDK, you can see Create BosClient Using STS.

View bucket permission

The following codes are used to view the bucket permission:

$response = $client->getBucketAcl($bucket);

The parameters that can be called in the parsing class returned by the getBucketAcl method are:

View Bucket Region

The bucket location is the bucket region. For the details of regions supported by Baidu AI Cloud, please see Instruction for Region Selection.

The following code is used to get the location information of this bucket:

$client->getBucketLocation($bucketName);

Create Bucket

You can create a Bucket using the following code:

$bucketName = "your_bucket";

// Does a bucket exist? If not, create a bucket.
$exist = $client->doesBucketExist($bucketName);
if(!$exist){
    $client->createBucket($bucketName);
}

Notes: Because the bucket name is unique in all regions, you need to ensure that bucketName is not the same as the bucket name in all other regions.

There are the following naming conventions for buckets:

• It can include lowercase letters, and numbers, and hyphens (-) only.
• It must start with a lowercase letter or number.
• It has a length of 3- 63 characters.

For the bucket created through the codes above, the permission is private read-write, and the storage class is standard storage (Storage). Users can specify the bucket permission and storage class when they create the bucket on the console.

Enumerate Buckets

The following code is used to list all buckets for users:

$response = $client->listBuckets();
foreach ($response->buckets as $bucket) {
    print $bucket->name;
}

Delete Bucket

Delete specified bucket

You can delete a Bucket using the following codes:

$bucketName = "your_bucket";
$client->deleteBucket($bucketName);

Notes:

• Before deletion, you need to ensure that all objects in this bucket and the uncompleted three-step upload parts have been deleted. Otherwise, the deletion fails.
• Before deletion, confirm that the Cross-origin replication is not enabled for this bucket, and this bucket is not the source bucket or target bucket in the cross-origin replication rules. Otherwise, it cannot be deleted.

Delete all buckets

You can delete all buckets through the combination of deleteBucket and listBuckets functions, whose codes are as follows:

    //List all buckets
    $response = $client->listBuckets();

    // Go through it to delete all buckets.
    foreach ($response->buckets as $bucket) {
        $marker = null;
        while (true) {
            $options = array();
            if ($marker !== null) {
                $options[BosOptions::MARKER] = $marker;
            }
            $response = $client->listObjects($bucket->name, $options);
            foreach ($response->contents as $object) {
                $client->deleteObject($bucket->name, $object->key);
            }
            if ($response->isTruncated) {
                $marker = $response->nextMarker;
            } else {
                break;
            }
        }
        $client->deleteBucket($bucket->name);
    }

Judge Whether Bucket Exists

If users want to judge whether a bucket exists, it can be implemented through the following code:

$client->doesBucketExist($bucketName);

Bucket Synchronization Data

The bucket data synchronization realizes the automatic synchronization of data in different buckets. It supports the customization of synchronization mode by setting specific rules. There are two types of synchronized data: stock data and incremental data. The following shows the usage method:

Create data synchronization

    $replication_rule = array(
            'status' => 'enabled',
            'replicateDeletes' => 'enabled',
            'id' => 'sample'
            );
    $replication_rule['resource'][0] = $raw_bucket . "/*";
    $replication_rule['destination']['bucket'] = $target_bucket;
    $replication_rule['replicateHistory']['bucket'] = $target_bucket;
    $bj_client->putBucketReplication($raw_bucket, $replication_rule);

Get bucket information for data synchronization

$response = $bj_client->getBucketReplication($raw_bucket);

Delete data synchronization and replication configuration

$response = $bj_client->deleteBucketReplication($raw_bucket);

Get process status of bucket data synchronization

$response = $bj_client->getBucketReplicationProgress($raw_bucket);

Bucket Lifecycle Management

A piece of data has its lifecycle. The lifecycle can be considered as a complete cycle from creation to archive and deletion. At the beginning of creation, the data often needs to be accessed and read frequently. Then, it is quickly cooled and archived and deleted finally. The lifecycle management is that the BOS service helps users to automatically manage the lifecycle of data. In general, it can serve for the following scenarios:

1. The data is automatically archived or deleted after it reaches a certain service life.
2. It specifies the time to perform the operation.

Create lifecycle configuration

A lifecycle configuration is created through the following codes:

$lifecycle_rule = array(
    array(
        'id' => 'rule-id0',
        'status' => 'enabled',
        'resource' => array(
            $this->bucket.'/prefix/*',
        ),
        'condition' => array(
            'time' => array(
                'dateGreaterThan' => '2016-09-07T00:00:00Z',
            ),
        ),
        'action' => array(
            'name' => 'DeleteObject',
        )         
    ),
    array(
        'id' => 'rule-id1',
        'status' => 'disabled',
        'resource' => array(
            $this->bucket.'/prefix/*',
        ),
        'condition' => array(
            'time' => array(
                'dateGreaterThan' => '2016-09-07T00:00:00Z',
            ),
        ),
        'action' => array(
            'name' => 'Transition',
            'storageClass' => 'COLD',
        ),      
    ), 
);
// Set the lifecycle rules.
$client->putBucketLifecycle($bucket, $lifecycle_rule);

Notes:

1. Only the bucket owner with the FULL_CONTROL permission can perform this operation.
2. "Resource" indicates which resources the rules are effective for. For example, it is effective for objects withprefix/insamplebucket/prefix/* and for all objects in samplebucket/*.

For the detailed explanation and configuration considerations of lifecycle management function related parameters, please see PutBucketLifecycle Interface.

Read lifecycle configuration of bucket

The following code is used to read the lifecycle configuration of the buckets:

$response = $client->getBucketLifecycle($bucket);

Delete lifecycle of bucket

The following code is used to delete the lifecycle of buckets:

$client->deleteBucketLifecycle($bucket);

Bucket Cross-origin Resource Access

CORS allows the Web application to access the resources that do not belong to this origin. BOS provides APIs to facilitate developers to carry out various cross-origin resource access controls.

Set CORS rules

The following codes are used to set a CORS rule:

$cors_rule = array(
    array(
        'allowedOrigins' => array(
            'http://www.example.com',
            'www.example2.com'
        ),
        'allowedMethods' => array(
            'GET',
            'HEAD'
        ),
        'allowedHeaders' => array(
            'Authorization'
        ),
        'allowedExposeHeaders' => array(
            'user-custom-expose-header'
        ),
        'maxAgeSeconds' => 3600        
    ),
    array(
        'allowedOrigins' => array(
            'http://www.example3.com'
        ),
        'allowedMethods' => array(
            'GET',
            'PUT'
        ),
        'allowedHeaders' => array(
            'x-bce-test'
        ),
        'allowedExposeHeaders' => array(
            'user-custom-expose-header'
        ),
        'maxAgeSeconds' => 3600        
    )
);
$client->putBucketCors($bucket, $cors_rule);

Notes:

1. If the original rule already exists, overwrite the original rule.
2. Only the bucket owner and the user with the FULL_CONTROL permission can set the CORS rules of the bucket. If users have no permission, it returns “403 Forbidden: AccessDenied”.

For the detailed explanation of CORS rule related parameters, please see PutBucketCors Interface.

Get CORS rules of buckets

The following code is used to get the CORS configuration of the buckets:

$response = $client->getBucketCors($bucket);

Disable CORS feature of buckets and Clear all rules

The following code is used to disable the CORS function of buckets and clear all rules:

$client->deleteBucketCors($bucket);

Bucket Server Encryption

BOS allows users to carry the HTTP header of x-bce-server-side-encryption in the upload and copy requests (PutObject, PostObject, InitiateMultipartUpload, AppendObject, FetchObject, and CopyObject) and specify the user's encryption algorithm (at present, only AES256 is supported) to realize the effective security protection of data.

Enable server encryption of buckets

The following code is used to enable the server encryption function of buckets:

$client->putBucketEncryption($bucket, 'AES256');

Get server encryption information of buckets

The following code is used to get the server encryption related information of buckets, including encryption algorithm:

$response = $client->getBucketEncryption($bucket);

Disable server encryption of buckets

The following code is used to disable the server encryption function of buckets:

$client->deleteBucketEncryption($bucket);

Access Log Rules of Buckets

When users want to track the request to access BOS, they can enable the access log function of buckets. Each access log records the details of a single access request, including requester, bucket name, request time, and request operation. The logging function can be applied to access statistics and security audit. When a bucket enables the access log function, it automatically generates the log files for the access request to this bucket according to the fixed naming rules (in hours) and writes them into the user-specified bucket.

Enable access logging of buckets

The following codes are used to open the access log of buckets and specify the bucket for storing the log and the file prefix for accessing the log:

$logging = array(
        'targetBucket' => $bucket.'logging',
        'targetPrefix' => 'TargetPrefixName'
);
$client->putBucketLogging($bucket, $logging);

Get access log configuration of buckets

The following code is used to get the access log configuration of a bucket:

$response = $client->getBucketLogging($bucket);

Disable access logging feature of bucket

$client->deleteBucketLogging($bucket);

Cross-origin Replication Rules of Buckets

Set cross-origin replication rules

The following codes are used to set the cross-origin replication rules for bj_bucket, and the target bucket is gz_bucket.

$replication_rule = array(
            'status' => 'enabled',
            'replicateDeletes' => 'enabled',
            'id' => 'sample'
        );
$replication_rule['resource'][0] = $bj_bucket . "/*";
$replication_rule['destination']['bucket'] = $gz_bucket;
$replication_rule['replicateHistory']['bucket'] = $gz_bucket;
$bj_client->putBucketReplication($bj_bucket, $replication_rule);

Get cross-origin replication rules

The following code is used to get the bucket information for data synchronization, including source bucket name, target bucket name, storage class, history replication, and data synchronization strategy.

$response = $bj_client->getBucketReplication($bj_bucket);

Get cross-origin replication progress

The following code can be used to get the process status of data synchronization replication:

$response = $bj_client->getBucketReplicationProgress($bj_bucket);

Delete cross-origin replication rule

The following code can be used to delete the data synchronization replication configuration:

$bj_client->deleteBucketReplication($bj_bucket);

Static Website Hosting of Buckets

BOS supports users to host the static website on the bucket to realize the lightweight operation of the website. After the setting is effective, users can access this hosting website by accessing the domain name of this bucket directly.

Setting static website hosting rules of buckets

Users must have the FULL_CONTORL permission on the bucket. It is not recommended to set the archive file. The archive file is not unreadable when it is not retrieved, and StaticWebsite is not effective at this time?.

$static_website = array(
        'index' => 'index.html',
        'notFound' => '404.html'
);
$client->putBucketStaticWebsite($bucket, $static_website);

Get static website hosting rules of buckets

$response = $client->getBucketStaticWebsite($bucket);

Delete static website hosting rules of buckets

$client->deleteBucketStaticWebsite($bucket);

Bucket Trash Rules

To improve the data reliability of BOS, BOS can perform the trash feature. The bucket owner with FULL_CONTROL permission of buckets can configure the bucket trash.

Enable Bucket Trash feature

To enable the Bucket Trash feature, users must be the source bucket owner with FULL_CONTROL permission and the destination bucket owner.

$client->putBucketTrash($bucket, '.trashDirName');

Remark: If the Bucket Trash feature is enabled, the original directory name is overwritten. The Bucket Trash feature cannot be enabled for archive storage files. When the archive storage files are deleted, this feature is deleted directly.

Get Bucket Trash enabling status

Get the Bucket Trash enabling status, and return the current trash directory name, which is .trash by default. The user must be the source bucket owner with the FULL_CONTROL permission and the destination bucket owner.

$response = $client->getBucketTrash($bucket);

Disable Bucket Trash feature

To disable the trash feature, users must be the source bucket owner with FULL_CONTROL permission and the destination bucket owner.

$client->deleteBucketTrash($bucket);

Copyright Protection Feature of Buckets

BOS supports the copyright protection feature through API, and it can specify the effective range of this feature through the resource field. For the file with copyright protection enabled, the anonymous download and access to this file or the access with custom photo processing parameters are not allowed. Only style access or access with a valid signature is allowed.

Enable copyright protection feature of buckets

The following codes can be used to enable the copyright protection feature of buckets and specify the resource field to indicate the effective resource range. For the file with copyright protection enabled, the anonymous download and access to this file or the access with custom image processing parameters are not allowed. Only style access or access with a valid signature is allowed.

$copyright_protection = array(
        $this->bucket.'/prefix/*',
        $this->bucket.'/*/suffix'
);
$client->putBucketCopyrightProtection($bucket, $copyright_protection);

Get copyright protection configuration of buckets

$response = $this->client->getBucketCopyrightProtection($this->bucket);

Disable copyright protection feature of buckets

$client->deleteBucketCopyrightProtection($bucket);

Set Bucket Type

Set storage class of buckets

$client->putBucketStorageClass($bucketName,$storageClass);

Get storage class of buckets

$client->getBucketStorageClass($bucketName)