Bucket操作

简介

Bucket是存放数据的容器,可以当成是存储桶。Bucket具有区域属性,只能位于一个区域。因为Bucket名称创建后不能修改名称和所属区域,所以建议根据业务情况就近存储,方便上传和下载以提高访问速度。Bucket名称具有全局唯一性。每个Object必须都包含在某个Bucket中。

一个用户最多可创建100个Bucket,但每个Bucket中存放的Object的数量和大小总和没有限制,用户不需要考虑数据的可扩展性。

说明:为保证良好的性能,建议用户在每个Bucket下上传的Object数量不要超过1000万。

有关Bucket的系统限制,请参见资源数目及大小规范

具体操作,请参见:

创建Bucket

在BOS中,用户操作的基本数据单元是Object,每个Object必须都包含在某个Bucket中,所以用户要存储数据,必须要创建Bucket。

BOS同时支持使用API与使用SDK创建Bucket,具体如下:

下面是使用Java SDK的代码示例:

public void createBucket (BosClient client, String bucketName) {
    // 新建一个Bucket
    client.createBucket(bucketName);
}

查看Bucket列表

用户创建Bucket之后,可以查看用户所拥有的所有Bucket列表。

BOS同时支持使用API与使用SDK列出Bucket,具体如下:

下面是使用Java SDK的代码示例:

public void listBuckets (BosClient client) {
    // 获取用户的Bucket列表
    List<BucketSummary> buckets = client.listBuckets().getBuckets();

    // 遍历Bucket
    for (BucketSummary bucket : buckets) {
        System.out.println(bucket.getName());
    }
}

删除Bucket

由于一个用户可创建的Bucket有配额限制(目前为100个),当某个Bucket不再使用时,用户可通过删除Bucket释放配额。

BOS同时支持使用API与使用SDK删除Bucket,具体如下:

下面是使用Java SDK的代码示例:

public void deleteBucket (BosClient client, String bucketName) {
    // 删除Bucket
    client.deleteBucket(bucketName);
}

跨区域复制

简介

BOS的跨区域同步功能可以在不同region间按照用户设置的逻辑异步复制Object或者Bucket,它可将源Bucket中的对象的改动(新建、覆盖、删除等)及历史数据同步到目标Bucket。该功能能够有效帮助用户完成源Bucket的合规性容灾,以及目标Bucket数据的高效使用。目标Bucket中的对象是源Bucket中对象的同步副本,它们具有相同的对象名、元数据以及内容。

应用场景

  • 高效访问,减少延迟:跨region访问Bucket或者Object,访问速度会因地理上的差异而降低。通过跨区域同步功能可提前将需要的数据同步至目标region,提高访问效率。
  • 合规性容灾:基于金融、政府等行业的合规性要求,在同一region中虽然有数据多副本设置。但为了防止洪水、地震等机房级别灾害,也要求数据跨region保存一份副本,BOS的跨区域同步功能提供了这样的能力。
  • 跨区域数据复用:由于业务原因例如跨region搭建的计算集群需要使用同一组数据等场景,可以使用BOS跨区域同步功能复制数据副本。

功能说明

跨区域同步支持不同region间两个指定Bucket的同步,可以通过配置将源Bucket的指定数据实时同步到目的Bucket。目前支持特性:

  • 数据实时自同步:用户可根据需要,将同步策略设置为全量同步(增/删/改动作都会同步)或写同步(增/改动作会同步)
  • 历史数据迁移:迁移历史数据,让原来Bucket中历史数据也能进行同步,形成相同的两份数据。
  • 指定目标存储类型:数据同步过程中可以指定存储类型和源Bucket一致,也可以根据需要选择不同的存储类型。

限制说明

  • BOS的Bucket同步功能采用异步复制逻辑,源Bucket数据复制到目标Bucket需要一定的时间,通常几分钟到几小时不等,取决于数据的大小。
  • 对于跨区域同步中的目标Bucket,复制过去的Object可能会覆盖目的Bucket中同名的Object,使用中请注意。
  • 跨区域同步策略的两个Bucket不能是另一条跨区域同步策略中的源bucket或目标Bucket。
  • 开启了启跨区域同步策略的Bucket不能被删除。如需删除Bucket,需先关闭跨区域同步策略。
  • 开启数据同步的两个Bucket必须分属两个区域,同区域的Bucket不能进行数据同步。

设置服务端加密

BOS支持用户在上传和复制请求(PutObject、PostObject、InitiateMultipartUpload、AppendObject、FetchObject、CopyObject)中携带x-bce-server-side-encryption的HTTP header并指定用户的加密算法(目前仅支持AES256),从而实现数据的有效安全保护,相关API请参见Object相关接口

BOS在控制台上增加了Bucket级别的开关,用户可直接开启Bucket加密,从而实现该Bucket内后续所有上传和复制的文件自动进行加密。我们也提供了操作Bucket加密的API:

说明:

  • 如果Object的请求中通过携带x-bce-server-side-encryption HTTP header并指定加密,那么不管Bucket加密开关是否打开,该文件都会加密。
  • 如果Object请求中未指定加密,那么如果Bucket加密开关打开,该文件会加密。
  • Bucket加密开关状态变化,不会影响已有文件,仅会对新文件生效。

设置访问日志

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

说明:访问日志存储到目标Bucket是一个“尽力而为”的过程。大多数情况下,一个访问请求从发生,到对应日志存储到目标Bucket会在2-3个小时内完成。但受到网络环境等因素影响,有的日志可能会延迟较长时间才能存储到目标Bucket。

日志命名规则

存储访问日志记录的Object命名规则为<TargetPrefix><SourceBucketName>-YYYY-mm-DD-HH-MM-SS-UniqueString,例如mylog/mybucket-2016-05-17-10-00-00-00000。其中

  • TargetPrefix为用户指定的前缀,即示例中的mylog/;
  • SourceBucketName为源Bucket名称,即示例中的mybucket;
  • YYYY、mm、DD、HH、MM和SS分别表示该日志所记录访问请求中的最小时间戳对应的年、月、日、小时、分钟和秒;
  • UniqueString为BOS系统生成的字符串。用于唯一标识这个日志文件,即示例中的00000。

日志格式

输出字段 例子 说明
Time 2016-09-05T09:02:03+08:00 发起请求的时间
Bucket Owner 6c47a952db4444c5a097b41be3f24c94 Bucket的Owner ID
Bucket samplebucket 请求访问的Bucket名字
Key dir/sample.jpg 请求访问的Object名字
Reserve - 保留字段
Remote IP 111.30.20.12 请求者IP地址
Requester 6c47a952db4444c5a097b41be3f24c94 请求者的ID
Request ID a94dbe12-717e-4e72-bcf2-0aa4a3100360 用于唯一标志该请求的UUID,同Header中的x-bce-request-id
Operation GetObject 请求对应的API
Request Host bj.bcebos.com HTTP请求的Host请求头
Request URI "GET/v1/tables.xml" HTTP请求中的URI,需要用双引号引用
HTTP Status 200 BOS返回的HTTP状态码
Error Code InvalidURI BOS返回的错误码
Bytes Send 2314 用户从BOS下载的流量
Object Size 1024 Object大小,单位为Bytes
Total Time(ms) 11 从开始接收请求到相应返回的总时长,单位为毫秒
Server Cost Time (ms) 10 从接收完所有请求到开始响应用户请求的总时长,单位为毫秒。目前该字段取值为-
Referer "https://cloud.baidu.com/product/bos.html" HTTP请求的Referer请求头
User Agent "curl/7.33.0" HTTP请求的User Agent请求头
Storage Class STANDARD 对象的存储类型
Multiple Delete "abc%0Adef" Multiple Delete删除的对象信息,'%0A'为分隔符,用于分隔多个对象
Reserve - 保留字段
Reserve - 保留字段

日志样例:

2016-09-05T09:02:03+08:00 e18b593b12d01ae931b4cd938f4967b8 bos-logging - - 127.0.0.1 e18b593b12d01ae931b4cd938f4967b8 98a20094-2002-4950-899d-9347244c71da GetBucket bj.bcebos.com "/bos-logging?delimiter=%2F&maxKeys=1000&prefix=" object="-" 200 success 2335 - 10 - "-" "bce-sdk-python/0.8.9/2.7.3 (default, Jun 24 2016, 15:08:42) [GCC 3.4.5 20051201 (Red Hat 3.4.5-2)]/linux2" - - - -

说明:

  • 日志中各个字段由空格分隔。
  • BOS的Log中,某些字段可能存在空格,这些字段(如 “Referrer” )在生成的时候,外部通过引号包括。
  • Reserve字段为保留字段,Log中用 “-”表示。
  • BOS以小时为单位生成Bucket访问的Log文件,但并不表示这个小时的所有请求都记录在这个小时的Log文件内,也有可能出现在上一个或者下一个Log文件中。
  • BOS生成Log文件会占用目标Bucket的存储空间。日志访问功能是免费的,但日志所占用的存储空间还是照常计费。用户可以像操作普通Object一样操作日志文件。
  • 日志文件在目标Bucket生成后,BOS不会主动清理这些日志文件。

设置日志

设置访问日志有通过控制台设置API实现两种方式。

生命周期管理

存放在BOS上的文件通常会存在新建、归档、删除这样的生命周期过程。文件在新建时通常会被频繁读取访问,之后读取次数变少逐渐冷却,最终被删除。用户如果手工维护数据的生命周期,则费时费力;但如果不去维护,则数据始终存放在标准存储里会产生不菲的费用。BOS提供生命周期管理帮助用户自动化完成数据生命周期管理,实现数据从创建到归档到删除的自动流程,从而节约人力和金钱成本。

生命周期管理支持三种功能:

  1. 归档转“冷”的数据,即转换存储类型从标准存储到低频存储;
  2. 删除不再需要的数据;
  3. 清除过期的三步上传数据。

从场景上划分,生命周期管理支持两种模式:

  • 数据达到一定寿命后自动归档或删除。如定义所有创建时间超过30天的数据转存低频存储。
  • 指定时间执行操作。如在某个特定时刻将所有文件归档。

您可以通过Console控制台和API两种方式来使用生命周期功能:

  1. 通过Console控制台管理生命周期请参考管理生命周期
  2. 通过API管理生命周期,参考PutBucketlifecycleGetLifeCycleDeleteLifeCycle接口。下面重点介绍一下通过API管理生命周期时的规则文件语法。

BOS提供的生命周期管理服务通过定义规则,并为每条规则设定动作来实现。

注意:

  • BOS生命周期规则设置后会在一天内生效。
  • 规则生效后,BOS会对符合条件的Object进行相应的处理,但处理需要一定的时间(一般情况下为几小时),所以设置规则后不一定能马上看到效果。
  • 规则中计算的时间(即Object的“年龄”)以Object的创建时间为准,而不是生命周期规则的创建/修改时间。
  • BOS只保存文件的最后修改时间,即last-modified时间;如果用户不更新meta或者覆盖文件,那么last-modified就是创建时间。所以生命周期中的“创建时间”其实是last-modified时间。

规则定义

规则定义遵循以下原则:

  • 规则基于bucket定义;
  • 每个bucket可以有至多1000条规则项;

以下是一个生命周期规则示例,该规则附属于名为samplebucket的bucket,包含3条规则项:

  • 2016年9月7日后删除prefix1下的所有文件;
  • 自动将prefix2下创建超过30天的文件转入低频存储;
  • 自动清除prefix3下超过5天未完成的三步上传。
{
    "rule": [
        {
            "id": "sample-rule-delete-prefix", 
            "status": "enabled", 
            "resource": [
                "samplebucket/prefix1/*"
            ], 
            "condition": {
                "time": {
                    "dateGreaterThan": "2016-09-07T00:00:00Z"
                }
            }, 
            "action": {
                "name": "DeleteObject"
            }
        },
        {
            "id": "sample-rule-transition-prefix", 
            "status": "enabled", 
            "resource": [
                "samplebucket/prefix2/*"
            ], 
            "condition": {
                "time": {
                    "dateGreaterThan": "$(lastModified)+P30D"
                }
            }, 
            "action": {
                "name": "Transition",
                "storageClass": "STANDARD_IA"
            }
        },
        {
            "id": "sample-rule-abort-multiupload-prefix", 
            "status": "enabled", 
            "resource": [
                "samplebucket/prefix3/*"
            ], 
            "condition": {
                "time": {
                    "dateGreaterThan": "$(lastModified)+P5D"
                }
            }, 
            "action": {
                "name": "AbortMultipartUpload"
            }
        }
    ],
}

每条规则由id、status、resource、condition和action组成,详细解释参见下表。

规则项 描述 是否必填 备注
id 规则的标识符。 可选 同一个bucket内规则id必须唯一,不能重复。如果用户不填系统会自动帮用户生成一个。
status 规则的状态。 必填 取值为enableddisabled,当规则处于disabled时规则不生效。
resource 规则对哪些资源生效。 必填 举例:对samplebucket里以prefix/为前缀的Object生效:samplebucket/prefix/*;对samplebucket里所有Object生效:samplebucket/*
condition 规则依赖的条件。 必填 目前只支持time形式。
+time 时间限制条件。 必填 通过定义的dateGreaterThan实现。
++dateGreaterThan 描述时间关系。 必填 支持绝对时间date和相对时间days。绝对时间date格式为yyyy-mm-ddThh:mm:ssZ,eg. 2016-09-07T00:00:00Z。绝对时间为UTC时间, 必须以00:00:00(UTC 0点)结尾;相对时间days的描述遵循ISO8601, 支持的最小时间粒度为天,如:$(lastModified)+P7D表示的时间为object的last-modified之后7天。
action 对resource执行的操作动作。 必填 -
+name 执行的操作名称。 必填 取值为TransitionDeleteObjectAbortMultipartUpload
+storageClass Object的存储类型 可选 action为Transition时可以设定,取值为STANDARD_IA,表示从标准类型转为低频存储类型, 取值为COLD,表示从标准类型转为冷存储类型。

action

BOS支持Transition、DeleteObject、AbortMultipartUpload三种操作,三种动作的详细解释如下:

操作 描述 备注
Transition 将resource转换存储类型。 - 文件在标准存储中存储时长必须大于7天才会被转为低频存储。因为文件创建后的7天通常为频繁访问期,转换成低频可能会增加成本。文件在低频存储中保存时间大于30天才会被转为冷存储, 因为在低频存储可能还会有低频度的访问需求, 如果转换成冷存储可能会增加成本
- 通过生命周期转成低频时,文件的last-modified不会更改。
DeleteObject 将resource删除。 根据设定的规则删除resource。低频存储有30天的最低保存时间,所以用户如果创建规则去删除一个存储时长不到30天的低频文件,会产生额外花费。
AbortMultipartUpload 清除一段时间内还没有完成的三步上传。 需要设置放弃分块上传的时间days。

dateGreaterThan

BOS支持绝对时间date和相对时间days两种形式的dateGreaterThan设置,注意事项如下:

dateGreaterThan项 描述 支持动作 备注
days 数据达到lastModified+days后执行操作。 支持transition、expiration、abortMultipartUpload三种操作。
- 使用days进行生命周期管理的文件,其操作执行时间是:文件的Last-modified加上days,再取整到下一个UTC午夜零点。例如,一个Object的最后更新时间是UTC的2014年4月12日上午1点,相匹配的规则定义的天数是3天,执行操作的时间是UTC 2014年4月16日0点整。
- 如果之后文件的last-modified发生修改,如meta更新、数据overwrite,那么操作的执行时间也会随之变化。
date 在指定日期执行操作。 支持transition和expiration两种操作。
- 如果指定date,date必须是UTC午夜零点,并且符合形如2014-01-01T00:00:00.000Z的ISO8601格式。
- date规则只会对Last-modified时间早于或等于date的文件生效。
- date规则会在当前时间>=date执行。
- 当date和“标准存储存够7天”冲突时,优先“标准存储存够7天”。

说明:

  • 每条规则里只能包含一个action。
  • 每个resource每种action最多只能有一条规则,例如bucket/prefix1/*不能有两条transition规则,但可以有一条transition规则加一条expiration规则。
  • 规则中如果以prefix定义的作用范围有包含关系,对于被包含的prefix以最小的作用范围定义的动作为准。如规则1定义prefix是 p1/p1/ 的Object 10天后delete,规则2定义prefix是 p1/p1/p1/的Object 15天后delete,规则1的prefix包含规则2的prefix,对于prefix为 p1/p1/p1/ 的Object执行15天后delete,对于p1/p1/中除了p1/p1/p1/之外的Object执行10天后delete动作。
  • 如果使用date作为Condition时,如“folder/”为prefix的文件,在30天后转低频,并于2016.8.17号删除。系统会依据规则计算出每个文件执行相应操作的时间,并对时间进行比对。如果文件同一天执行transition和expiration,则直接删除;如果文件删除时间早于转低频时间,也直接删除。

回收站设置

应用场景

当开发者在BOS进行数据存储和管理时,基于更高的数据可靠性要求,通常希望如下场景有更好的解决方案:

  1. 当使用数据时产生误删情况,希望有途径将数据找回;
  2. 当一个Bucket通过ACL授权给多个用户,并给予他们Write权限时,希望能够避免这些用户对Bucket中的数据进行恶意删除操作。

使用方法

基于上述场景为了提升BOS的数据可靠性,BOS提供了回收站功能,Bucket的Owner且对Bucket具备Full Control权限的用户可对Bucket进行回收站相关的配置。配置方法可根据开发习惯,使用API或控制台等多种方式:

  1. 当Bucket开启回收站功能后,用户即可在该Bucket的回收站目录中查找到Bucket中被删除的数据。该回收站路径默认为Bucket/.trash/
  2. 如果您需要将回收站内的数据进行恢复,则直接rename该回收站内的文件,将其文件名中的.trash/路径去除即可
  3. 如果您需要将回收站内的数据进行彻底清除,则直接将.trash/路径下的某文件再次delete即可

同时,基于上述应用场景中的第二种情况,您也可以将回收站能力与Bucket ACL做一些组合,例如为某需要在BucketA中有Write权限的用户,配置如下ACL:

{
  "id": "policy_3563bce24f2049629f4e0b6bf7a2775d",
  "version": "v1",
 "grantee": [
                {
                    "id": "b124deeaf6f641c9ac27700b41a350a8"
                }
            ],
  "accessControlList": [
    {
      "service": "bce:bos",
      "region": "bj",
      "resource": [
        "BucketA"
      ],
      "effect": "Allow",
      "permission": [
        WRITE"
      ]
    },
    {
      "service": "bce:bos",
      "region": "bj",
      "resource": [
        "BucketA/.trash/"
      ],
      "effect": "Deny",
      "permission": [
        "DeleteObject"
      ]
    }
  ]
}

通过上述ACL,该用户可对Bucket进行写入和删除行为,但对于回收站内的数据无法进行二次彻底删除。

注意:

  1. 当Bucket已开启回收站功能并设置回收站路径为.trash/,之后将Bucket内的文件A删除(原文件路径为Bucket/test/A),则该文件A的路径变为Bucke/.trash/test/A,之后您关闭该Bucket的回收站,则该文件A在Bucket中的保留路径仍为Bucket/.trash/test/A。因此,提醒您在关闭回收站功能后,同时按需将类似垃圾文件清除。
  2. 当Bucket已开启回收站功能并设置回收站路径为.trash/,删除后的文件将进入Bucket/.trash/目录下,之后您将回收站文件路径更改为.trashX/,路径变更前的回收站文件将保留在原位置,即Bucket/.trash/路径下,而之后被删除的文件,将进入Bucket/.trashX/路径下。因此,提醒您在变更回收站路径时,对回收站内原有文件按需进行搬迁。

收费模式

  • BOS回收站不另外收费,回收站内的文件还视为Bucket内数据的一部分,按照其存储类型收取容量费用。
  • 当回收站内的文件被彻底清除后,将不收取容量费用。

CDN加速

BOS目前支持使用CDN对指定Bucket进行加速,用户选择需要加速的Bukcet后,BOS将对应Bucket的域名的DNS解析修改为CDN提供的CNAME域名,从而接入CDN节点,开启CDN加速。

CDN加速目前只支持通过控制台进行操作,具体操作请参见CDN加速发布

跨域访问

跨域访问是指发起请求的资源所在域不同于该请求所指向的资源所在域,出于安全考虑,浏览器会限制这种非同源的访问。而在实际应用中,会经常遇到跨域访问的请求,例如,用户的网站A(http://domainA.example)后端使用了BOS存储,用户想在该网站的Web应用程序中引用存储在BOS上的资源,但该页面只能向网站域名http://domainA.example发起请求,向其他网站发送的请求均会被浏览器限制。

跨域资源共享(Cross-Origin Resource Sharing),简称CORS,是HTML5提供的标准跨域解决方案,BOS目前已经支持CORS标准来实现跨域访问。具体的CORS规则可以参考W3C CORS规范。CORS通过HTTP请求中附带Origin的Header来表明自己来源域,比如上面那个例子,Origin的Header就是http://domainA.example。服务器端接收到这个请求之后,会根据一定的规则判断是否允许该来源域的请求,如果允许的话,服务器在返回的响应中会附带上Access-Control-Allow-Origin这个Header,内容为http://domainA.example来表示允许该次跨域访问。如果服务器允许来自任何域名的跨域请求,则可将Access-Control-Allow-Origin的Header设置为 * 即可,浏览器根据是否返回了对应的Header来决定该跨域请求是否成功,如果没有附加对应的Header,浏览器将会拦截该返回结果。如果是非简单请求,浏览器会先发送一个OPTIONS请求(预请求)来探测这个跨域请求对于服务器端是不是安全可接受的,如果服务器不支持接下来的操作,浏览器会拦截该跨域请求。
BOS支持CORS规则的配置,请参考跨域资源共享

说明

  • CORS只针对浏览器环境有意义,相关的Header附加由浏览器自动完成,不需要用户手动操作。
  • CORS请求与BOS的身份验证是完全独立的,即CORS规则仅仅是用来决定是否附加CORS相关的Header的一个规则,是否拦截该请求完全由浏览器决定。
  • 使用跨域请求的时候需要关注浏览器是否开启了Cache功能。当运行在同一个浏览器上分别来源于不同域 http://domainA.examplehttp://domainB.example 的两个页面都同时请求同一个跨域资源的时候,如果http://domainA.example的请求先到达服务器,服务器将资源带上Access-Control-Allow-Origin的Header为 http://domainA.example 返回给用户。这个时候 http://domainB.example 又发起了请求,浏览器会将Cache的上一次请求结果返回给用户,这个时候Header的内容和CORS的要求不匹配,就会导致后面的请求失败。