Bucket管理

更新时间：2022-05-10

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

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

说明：

百度智能云目前开放了多区域支持，请参考区域选择说明。目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。
存储在BOS上的每个Object都必须包含在一个Bucket中。
一个用户最多可创建100个Bucket，但每个Bucket中存放的Object的数量和大小总和没有限制，用户不需要考虑数据的可扩展性。

Bucket权限管理

设置Bucket的访问权限

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

bos_client.set_bucket_canned_acl(bucket_name, canned_acl.PRIVATE)

其中canned_acl中包含三个参数：PRIVATE、PUBLIC_READ、PUBLIC_READ_WRITE，它们分别对应的相关权限为：private、public-read、public-read-write。关于权限的具体内容可以参考《BOS API文档使用CannedAcl方式的权限控制》。

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

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

bos_client.set_bucket_acl(
    bucket_name,
    [{'grantee': [{'id': 'b124deeaf6f641c9ac27700b41a350a8'},
                  {'id': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'}],
      'permission': ['FULL_CONTROL'],
      'resource':['your_bucket_name/prefix/*']
      }])

注意：

id为用户ID，您可在用户信息中查看。

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

set_bucket_acl()的第二个参数acl不需要包含"accessControlList"字段，已经封装到接口中。

设置更多Bucket访问权限

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

myAcl =[{"grantee":[{"id": "*"}], 
		"permission":["FULL_CONTROL"], 
		"condition":{
			"referer":{"stringEquals":["http://test/index"]}
			}
		}]
bos_client.set_bucket_acl(bucket_name, myAcl)

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

myAcl = [{"grantee":[{"id":"*"}], 
		"permission":["FULL_CONTROL"], 
		"condition":{"ipAddress":["192.170.0.6"]}
		}]
bos_client.set_bucket_acl(bucket_name, myAcl)

设置STS临时token权限

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

使用BOS Python SDK设置STS临时token权限可参考通过sts方式访问BOS

查看Bucket的权限

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

response = bos_client.get_bucket_acl(bucket_name)

bos_client.set_bucket_acl(bucket_name, response.access_control_list)

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

参数	说明
owner	Bucket owner信息
+id	Bucket owner的用户ID
access_control_list	标识Bucket的权限列表
+grantee	标识被授权人
++id	被授权人ID
+permission	标识被授权人的权限
+resource	ACL配置项所影响的资源

查看Bucket所属的区域

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

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

region = bos_client.get_bucket_location(bucket_name)                  
print(region)

新建Bucket

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

if not bos_client.does_bucket_exist(bucket_name):
    bos_client.create_bucket(bucket_name)

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

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

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

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

列举Bucket

用如下方式可以列出用户所有的Bucket：

response = bos_client.list_buckets()
for bucket in response.buckets:
	 print(bucket.name)

list_buckets方法返回的解析类中可供调用的参数如下：

参数	说明
owner	Bucket Owner信息
+id	Bucket Owner的用户ID
+display_name	Bucket Owner的名称
buckets	存放多个Bucket信息的容器
bucket	存放一个Bucket信息的容器
+name	Bucket名称
+creation_date	Bucket创建时间
+location	Bucket所属的区域

删除Bucket

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

bos_client.delete_bucket(bucket_name)

注意：

如果Bucket不为空（即Bucket中有Object和未完成的三步上传Part存在），则Bucket无法被删除，必须清空Bucket后才能成功删除。

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

判断Bucket是否存在

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

    # 获取Bucket的存在信息,需要传入bucket名称，返回值为布尔型
    exists = bos_client.does_bucket_exist(bucket_name)
    # 输出结果
    if exists:
        print("Bucket exists")
    else:
        print("Bucket not exists")

设置Bucket存储类型

如果用户使用API、CLI或者SDK上传的Object未指定存储类型，则继承Bucket的默认存储类型。如果上传Object指定的存储类型和Bucket默认存储类型不一致时，以Object的存储类型为准。存储类型包含标准存储、低频存储、冷存储和归档存储四种，具体使用场景和性能请参见分级存储。

put_bucket_storage_class

本接口用来设置Bucket的默认存储类型。

 bos_client.set_bucket_storage_class(bucket_name, storage_class=storage_class.COLD)

get_bucket_storage_class

本接口用来获取Bucket的默认存储类型。

 response = bos_client.get_bucket_storage_class(bucket_name)

Bucket生命周期管理

应用场景

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

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

新建Lifecycle配置

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

rule = {}
rule['id'] = 'rule1'
rule['status'] = 'enabled'
rule['action'] = {}
rule['action']['name'] = 'Transition'
rule['action']['storageClass'] = 'STANDARD_IA'
#对baidubosmty2里所有Object生效
rule['resource'] = ['baidubosmty2/*']
rule['condition'] = {}
rule['condition']['time'] = {'dateGreaterThan': 'XXXX-XX-XXTXX:XX:XXZ'}
rules=[]
rules.append(rule)
bos_client.put_bucket_lifecycle(bucket_name, rules)

注意：

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

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

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

读取Bucket的Lifecycle配置

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

response = bos_client.get_bucket_lifecycle(bucket_name)

删除Bucket Lifecycle

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

bos_client.delete_bucket_lifecycle(bucket_name)

日志管理

put_bucket_logging

本接口用来开启Bucket的访问日志并指定存放日志的Bucket和访问日志的文件前缀。访问日志的规则请参见日志命名规则和日志格式。

bos_client.put_bucket_logging(source_bucket, target_bucket, prefix)

get_bucket_logging

本接口用来获取某个Bucket的访问日志配置情况。

response = bos_client.get_bucket_logging(bucket_name)

delete_bucket_logging

bos_client.delete_bucket_logging(bucket_name)

Bucket跨域资源访问

应用场景

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

设定CORS规则

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

conf = {}
conf['allowedOrigins'] = ['http://www.boluor.com']
conf['allowedMethods'] = ['GET', 'HEAD', 'DELETE']
conf['allowedHeaders'] = ['Authorization', 'x-bce-test', 'x-bce-test2']
conf['allowedExposeHeaders'] = ['user-custom-expose-header']
conf['maxAgeSeconds'] = 3600
confs = []
#每个Bucket最多允许有100条规则。
confs.append(conf)
bos_client.put_bucket_cors(bucket_name, confs)

注意:

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

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

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

获取Bucket的CORS规则

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

response = bos_client.get_bucket_cors(bucket_name)

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

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

bos_client.delete_bucket_cors(bucket_name)

数据同步

设置数据同步规则

参数	是否必须	描述
id	是	replication规则名，id 由数字字母 - _ 组成，不得超过20个字符
status	是	是否生效
resource	是	replication生效前缀，resource的配置形式为｛$bucket_name/<生效的对象前缀>｝，必须要以`$bucket_name`+`/`开头
destination	是	复制的目的端配置
+bucket	是	目的Bucket name
+storageClass	否	目的Object的存储类型。如果保持和源Bucket的存储类型一致，则该参数不需要配置；如果需要单独指定存储类型可以为`STANDARD`，`STANDARD_IA`，`COLD`；如果是多AZ类型bucket，可取值为`MAZ_STANDARD_IA`和`MAZ_STANDARD`。
replicateHistory	否	历史文件复制，有该项则认为是开启。开启历史文件复制后，存量的全部Object都同步复制到目的Bucket，复制范围共用resource。
+storageClass	否	目的Object的存储类型。如果保持和源Bucket的存储类型一致，则该参数不需要配置；如果需要单独指定存储类型可以为`STANDARD`，`STANDARD_IA`，`COLD`；如果是多AZ类型bucket，可取值为`MAZ_STANDARD_IA`和`MAZ_STANDARD`。
replicateDeletes	是	是否开启删除同步,可以为`enabled`,`disabled` 。

若用户需要开启Bucket之间的数据同步，则如下代码可以做到：

bucket_name = "<YOUR_BUCKET_NAME>"
rule_id = "sample-rep-config"
dst_bucket_name = "<DESTINATION_BUCKET_NAME>"
replication = {
      "status":"enabled",
      "resource":[
          bucket_name + "/*"
          ],
      "destination":
          {
              "bucket": dst_bucket_name,
              "storageClass":"COLD"
          },
      "replicateHistory":
          {
              "bucket": dst_bucket_name,
              "storageClass":"COLD"
          },
      "replicateDeletes":"enabled",
      "id": rule_id
      }
# test put bucket replication
bos_client.put_bucket_replication(bucket_name, replication)

获取指定的数据同步规则

若用户想获取bucket指定id的数据同步信息，包括源Bucket名称、目的Bucket名称、存储类型、是否进行历史复制、数据同步策略、目的region等。则如下代码所示：

response = bos_client.get_bucket_replication(bucket_name, id=rule_id)
print("id:{}, status:{}, resource:{}, destination:{}, replicateDeletes:{}, replicateHistory:{}".format(response.id, response.status, response.resource, response.destination, response.replicate_deletes, response.replicate_history))

删除指定的数据同步规则

若用户想删除bucket指定id的数据同步，则如下代码所示：

bos_client.delete_bucket_replication(bucket_name ,id=rule_id)

列举数据同步规则

若用户想获取bucket所有的replication同步规则，则如下代码所示：

response = bos_client.list_bucket_replication(bucket_name)
print(response.rules)

获取指定的数据同步规则的进程状态

若用户想获取指定id的数据同步复制的进程状态，则如下代码所示：

response = bos_client.get_bucket_replication_progress(bucket_name, id=rule_id)
print("status:{}, historyReplicationPercent:{}, latestReplicationTime:{}".format(response.status, response.history_replication_percent, response.latest_replication_time))

Bucket回收站

应用场景

为了提高 BOS 数据的可靠性，用户可以通过配置回收站(Bucket Trash)的功能，保证删除后的数据在回收站内继续保留，用于后续对删除数据的找回。用户必须是源Bucket的owner且拥有FULL_CONTROL权限，且是目标Bucket的owner。

注意：
1.进入回收站的文件仍然会继续计费，直到用户彻底删除。对于回收站中的文件，建议用户配置生命周期来删除过期的文件。
2.用户进行覆盖操作时，旧的数据不会进入回收站。

开通回收站

参数	是否必须	描述
trash_dir	否	指定回收站目录名，可选。回收站默认目录为".trash"。

若用户想开通Bucket回收站并指定回收站目录，则如下代码所示：

bos_client.put_bucket_trash(bucket_name, trash_dir=".trash")

注意：
1.若之前已开通过回收站功能，再次开通会覆盖原回收站目录名。
2.回收站目录名词只能包含字母、数字、中文、下划线（_）和短横线（-）、小数点（.）。包含'/'会报错。
3.开通了回收站功能的bucket，删除object会回到回收站中(回收站中的object的全称是：trashDir + '/' + old object name)。未开通此功能的bucket，或者开通此功能的bucket且删除回收站内的object时，会彻底删除。
4.归档类型文件不支持Bucket Trash功能，删除归档类型文件时会直接删除。

获取回收站开通信息

若用户想获取Bucket回收站开通信息，获取当前回收站目录名,则如下代码所示：

response = bos_client.get_bucket_trash(bucket_name)
print("trash_dir:", response.trash_dir)

关闭回收站

若用户想关闭Bucket回收站，则如下代码所示：

response = bos_client.delete_bucket_trash(bucket_name)

用户额度管理

put_user_quota

此接口用来设置用户的额度，额度包括总的bucket数及各个region总的存储容量，当前总的Bucket数最大值不能超过100，注意该接口只能被主用户调用，

参数	是否必须	描述
max_bucket_count	是	最大可以创建的bucket数，若为-1，则表示不设置
max_capacity_mega_bytes	是	单位为MB，表示最大的存储容量，若为-1或者0，表示不设置存储容量额度限制，即无上限

response = bos_client.put_user_quota(max_bucket_count, max_capacity_mega_bytes)

get_user_quota

此接口用来查看用户的额度设置，注意该接口只能被主用户调用。

response = bos_client.get_user_quota()
print("[Sample] get user quota maxBucketCount:", response.max_bucket_count)
print("[Sample] get user quota maxCapacityMegaBytes:", response.max_capacity_mega_bytes)

delete_user_quota

此接口用来删除额度设置，注意该接口只能被主用户调用。

response = bos_client.delete_user_quota()

事件通知

put_notification

本接口用于指定bucket上增加通知规则。

注意：

只有bucket owner或者full control权限才能获取这个bucket的配置。

如果不是bucket owner则返回403，如果对应的文件不存在则返回404。

相关参数的详细解释请参见PutNotification接口。

notifications = list()
notifications.append(
    {
        "resources": [
            "/"
        ],
        "encryption": {
            "key": "06a62b70f47dc4a0a7da349609f1a1ac"
        },
        "status": "enabled",
        "name": "name3",
        "id": "r3",
        "appId": "p3",
        "events": [
            "AppendObject",
            "CompleteMultipartUpload",
            "CopyObject",
            "PutObject",
            "PostObject",
            "FetchObject",
            "DeleteObject"
        ],
        "apps": [
            {
                "eventUrl": "http://www.liujiang.com",
                "id": "ImageCensor",
                "xVars": "{\"saveUrl\": \"http://xxx.com/ocr\"}"
            }
        ]
    })
response = bos_client.put_notification(bucket_name, notifications)

get_notification

本接口用于获取指定bucket上的通知规则。

response = bos_client.get_notification(bucket_name)

delete_notification

本接口用于删除指定bucket上的通知规则。

注意：
该接口为一次性全部删除当前bucket下全部规则

response = bos_client.delete_notification(bucket_name)

原图保护

put_bucket_copyright_protection

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

resource = [bucket_name + "/test/*"]
bos.put_bucket_copyright_protection(bucket_name, resource)

get_bucket_copyright_protection

此命令用来获取某个Bucket的原图保护配置情况。

response = bos.get_bucket_copyright_protection(bucket_name)

delete_bucket_copyright_protection

本接口用来关闭Bucket原图保护功能。

bos.delete_bucket_copyright_protection(bucket_name)

初始化

文件管理

百度智能云

对象存储 BOS

对象存储 BOS

Bucket管理

Bucket权限管理

设置Bucket的访问权限

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

设置更多Bucket访问权限

设置STS临时token权限

查看Bucket的权限

查看Bucket所属的区域

新建Bucket

列举Bucket

删除Bucket

判断Bucket是否存在

设置Bucket存储类型

put_bucket_storage_class

get_bucket_storage_class

Bucket生命周期管理

应用场景

新建Lifecycle配置

读取Bucket的Lifecycle配置

删除Bucket Lifecycle

日志管理