Bucket管理

更新时间：2023-03-13

Bucket既是BOS上的命名空间，也是计费、权限控制、日志记录等高级功能的管理实体。

Bucket名称在所有区域中具有全局唯一性，且不能修改。

说明：

百度智能云目前开放了多区域支持，请参考区域选择说明。 BOS区域与EndPoint的对应关系，请参考访问域名说明。

存储在BOS上的每个Object都必须包含在一个Bucket中。
一个用户最多可创建100个Bucket，但每个Bucket中存放的Object的数量和大小总和没有限制，用户不需要考虑数据的可扩展性。

Bucket权限管理

设置Bucket的访问权限

如下代码将Bucket的权限设置为了private：

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

其中CannedAcl.php中封装了三个参数：ACL_PRIVATE、ACL_PUBLIC_READ、ACL_PUBLIC_READ_WRITE，它们分别对应的相关权限为：private、public-read、public-read-write。关于权限的具体内容可以参考《BOS API文档使用CannedAcl方式的权限控制》。

设置指定用户对Bucket的访问权限

BOS提供setBucketAcl方法来实现指定用户对Bucket的访问权限设置，可以参考如下代码实现：

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

注意：

permission中的权限设置包含三个值：READ、WRITE、FULL_CONTROL，它们分别对应相关权限。具体内容可以参考《BOS API文档上传ACL文件方式的权限控制》。

设置两个以上（含两个）被授权人时，请参考以上示例的格式，若将数组合并会返回报错。

设置更多Bucket访问权限

通过设置referer白名单方式设置防盗链

$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);

限制客户端IP访问，只允许部分客户端IP访问

$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);

设置STS临时token权限

对于通过STS方式创建的临时访问身份，管理员也可进行专门的权限设定。 STS的简介及设置临时权限的方式可参见临时授权访问。

使用BOS PHP SDK设置STS临时token权限可参考使用STS创建BosClient

查看Bucket的权限

如下代码可以查看Bucket的权限：

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

getBucketAcl方法返回的解析类中可供调用的参数有：

参数	说明
owner	Bucket owner信息
id	Bucket owner的用户ID
acl	标识Bucket的权限列表
grantee	标识被授权人
-id	被授权人ID
permission	标识被授权人的权限

查看Bucket所属的区域

Bucket Location即Bucket Region，百度智能云支持的各region详细信息可参见区域选择说明。

如下代码可以获取该Bucket的Location信息：

$client->getBucketLocation($bucketName);

新建Bucket

如下代码可以新建一个Bucket：

$bucketName = "your_bucket";

//Bucket是否存在，若不存在创建Bucket
$exist = $client->doesBucketExist($bucketName);
if(!$exist){
    $client->createBucket($bucketName);
}

注意： 由于Bucket的名称在所有区域中是唯一的，所以需要保证bucketName不与其他所有区域上的Bucket名称相同。

Bucket的命名有以下规范：

只能包括小写字母，数字，短横线（-）。

必须以小写字母或者数字开头。

长度必须在4-63字节之间。

通过上述代码创建的bucket，权限是私有读写，存储类型是标准类型（Standard）。用户在控制台创建Bucket时可以指定Bucket权限和存储类型。

列举Bucket

如下代码可以列出用户所有的Bucket：

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

删除Bucket

删除指定Bucket

如下代码可以删除一个Bucket：

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

注意：

在删除前需要保证此Bucket下的所有Object和未完成的三步上传Part已经被删除，否则会删除失败。

在删除前确认该Bucket没有开通跨区域复制，不是跨区域复制规则中的源Bucket或目标Bucket，否则不能删除。

删除所有Bucket

将deleteBucket和listBuckets函数结合，可以删除全部Bucket，参考代码如下：

    //列出全部Bucket
    $response = $client->listBuckets();

    //遍历删除全部Bucket
    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);
    }

判断Bucket是否存在

若用户需要判断某个Bucket是否存在，则如下代码可以做到：

$client->doesBucketExist($bucketName);

Bucket数据同步

Bucket数据同步实现了不同Bucket内数据的自动同步，并且支持通过设置具体规则来定制同步方式。其中同步的数据分为两种，存量数据和增量数据。以下为使用方法：

创建数据同步

    $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);

获取数据同步的Bucket信息

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

删除数据同步复制配置

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

获取Bucket数据同步的进程状态

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

Bucket生命周期管理

一个数据是有其生命周期的，从创建到归档到删除可以认为是一个完整的循环。创建之初的数据往往需要频繁访问读取，之后迅速冷却归档，最终被删除。生命周期管理就是对象存储服务帮助用户自动化管理数据的生命周期。通常可以服务于以下场景：

数据达到一定寿命后自动归档或删除。
指定时间执行操作。

新建Lifecycle配置

如下代码新建了一个Lifecycle配置

$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',
        ),      
    ), 
);
// 设置生命周期规则
$client->putBucketLifecycle($bucket, $lifecycle_rule);

注意：

只有Bucket的Owner拥有full control才能够进行此操作。

"resource"指明规则对哪些资源生效。例如，对samplebucket里以prefix/为前缀的Object生效：samplebucket/prefix/*；对samplebucket里所有Object生效：samplebucket/*。

生命周期管理功能相关参数的详细解释及配置注意事项请参见：PutBucketLifecycle接口

读取Bucket的Lifecycle配置

如下代码可读取Bucket的Lifecycle配置

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

删除Bucket Lifecycle

如下代码可以删除Bucket的lifecycle:

$client->deleteBucketLifecycle($bucket);

Bucket跨域资源访问

跨域资源共享(CORS)允许WEB端的应用程序访问不属于本域的资源。BOS提供接口方便开发者控制跨域访问的各种权限。

设定CORS规则

如下代码设定了一个CORS规则：

$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);

注意：

如果原规则存在则覆盖原规则。

只有Bucket的所有者和被授予FULL_CONTROL权限的用户才能设置Bucket的CORS。没有权限时，返回403 Forbidden错误，错误码：AccessDenied。

CORS规则相关参数的详细解释请参见PutBucketCors接口

获取Bucket的CORS规则

如下代码可获取Bucket的CORS配置:

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

关闭Bucket的CORS功能并清空所有规则

如下代码可以关闭Bucket的CORS功能并清空所有规则:

$client->deleteBucketCors($bucket);

Bucket服务端加密

BOS支持用户在上传和复制请求（PutObject、PostObject、InitiateMultipartUpload、AppendObject、FetchObject、CopyObject）中携带x-bce-server-side-encryption的HTTP header并指定用户的加密算法（目前仅支持AES256），从而实现数据的有效安全保护。

开启Bucket的服务端加密

如下代码可以开启bucket服务端加密功能

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

获取Bucket服务端加密信息

如下代码可以获取bucket服务端加密相关信息，包括加密算法等

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

关闭Bucket的服务端加密

如下代码可以关闭bucket服务端加密功能

$client->deleteBucketEncryption($bucket);

Bucket访问日志规则

当用户需要跟踪访问BOS的请求时可以对Bucket开启访问日志功能。每条访问日志记录了单个访问请求的详细信息，包括请求者、Bucket名称、请求时间和请求操作等。日志记录功能可以应用在访问统计和安全审核等方面。当一个Bucket开启访问日志功能后，会自动将对这个Bucket的访问请求，以小时为单位，按照固定的命名规则，生成日志文件写入用户指定的Bucket。

开启Bucket的访问日志

如下代码可以开启Bucket的访问日志并指定存放日志的Bucket和访问日志的文件前缀

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

获取Bucket的访问日志配置情况

如下代码可以获取某个Bucket的访问日志配置情况

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

关闭Bucket访问日志记录功能

$client->deleteBucketLogging($bucket);

Bucket跨区域复制规则

设置跨区域复制规则

如下代码给bj_bucket设置跨区域复制规则，目的bucket是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);

获取跨区域复制规则

如下代码用来获取数据同步的Bucket信息，包括源Bucket名称、目的Bucket名称、存储类型、是否进行历史复制，数据同步策略等

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

获取跨区域复制进度

如下代码可以用来获取数据同步复制的进程状态

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

删除跨区域复制规则

如下代码可以删除数据同步复制配置

$bj_client->deleteBucketReplication($bj_bucket);

Bucket托管静态网站

BOS支持用户将静态网站托管在Bucket上，实现网站轻量化运维。设置生效后，用户可通过直接访问该Bucket的域名访问该托管网站。

设置bucket静态网站托管规则

用户必须对bucket 具有 full control 权限。不建议设置归档文件，归档文件没有取回时不可读，StaticWebsite此时不会生效。

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

获取bucket静态网站托管规则

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

删除bucket静态网站托管规则

$client->deleteBucketStaticWebsite($bucket);

Bucket回收站规则

为了提升BOS的数据可靠性，BOS提供了回收站功能，Bucket的Owner且对Bucket具备Full Control权限的用户可对Bucket进行回收站相关的配置。

开通Bucket Trash功能

开通Bucket Trash功能，用户必须是源Bucket的owner且拥有FULL_CONTROL权限，且是目标Bucket的owner。

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

备注： 若已开通trash功能，会覆盖原目录名。归档类型文件不支持Bucket Trash，删除归档类型文件时会直接删除。

获取Bucket Trash开通状态

获取Bucket Trash开通状态，返回当前trash目录名，默认为.trash。用户必须是源Bucket的owner且拥有FULL_CONTROL权限，且是目标Bucket的owner。

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

关闭Bucket Trash功能

关闭trash功能，用户必须是源Bucket的owner且拥有FULL_CONTROL权限，且是目标Bucket的owner。

$client->deleteBucketTrash($bucket);

Bucket原图保护功能

BOS支持通过API实现原图保护功能，并可通过resource字段指定该功能生效范围。对于开通原图保护的文件，不允许匿名下载访问该文件，或带自定义图片处理参数访问，只允许使用style样式访问或携带合法签名访问。

开启Bucket的原图保护功能

如下代码可以开启Bucket的原图保护功能，并指定resource字段，表示生效的资源范围。对于开通原图保护的文件，不允许匿名下载访问该文件，或带自定义图片处理参数访问，只允许使用style样式访问或携带合法签名访问。

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

获取Bucket的原图保护配置情况

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

关闭Bucket原图保护功能

$client->deleteBucketCopyrightProtection($bucket);

设置Bucket存储类型

设置bucket存储类型

// STANDARD代表标准存储，STANDARD_IA代表低频存储，COLD代表冷存储，ARCHIVE代表归档类型；
// 对于多AZ类型bucket，只允许设置MAZ_STANDARD和MAZ_STANDARD_IA两种存储类型
$storageClass = "STANDARD";
$client->putBucketStorageClass($bucketName, $storageClass);

获取bucket的存储类型

$client->getBucketStorageClass($bucketName)

初始化

文件管理

对象存储 BOS