文件管理
上传文件
在BOS中，用户操作的基本数据单元是Object。Object包含Key、Meta和Data。其中，Key是Object的名字；Meta是用户对该Object的描述，由一系列Name-Value对组成；Data是Object的数据。
BOS PHP SDK提供了丰富的文件上传接口，可以通过以下方式上传文件：
- 简单上传
- 追加上传
- 分片上传
- 大文件上传
- 断点续传上传
简单上传
BOS在简单上传的场景中，支持以指定文件形式、以数据流方式、以二进制串方式、以字符串方式执行Object上传，请参考如下代码：
1// 以数据流形式上传Object
2$string = "myobjectcontent";
3$length = Strlen($string);
4$md5 = base64_encode(md5($string,true));
5$data = file_get_contents("myfile","rb");
6$client->putObject($bucketName, $objectKey, $data, $length, $md5);
7
8// 从字符串中上传Object
9$client->putObjectFromString($bucketName, $objectKey, $string);
10
11// 从文件中直接上传Object
12$client->putObjectFromFile($bucketName, $objectKey, $fileName);Object以文件的形式上传到BOS中，putObject相关接口支持不超过5GB的Object上传。在PutObject请求处理成功后，BOS会在Header中返回Object的ETag作为文件标识。
设置文件元信息
文件元信息(Object Meta)，是对用户在向BOS上传文件时，同时对文件进行的属性描述，主要分为分为两种：设置HTTP标准属性（HTTP Headers）和用户自定义的元信息。
设定Object的Http Header
BOS PHP SDK本质上是调用后台的HTTP接口，因此用户可以在上传文件时自定义Object的Http Header。常用的http header说明如下：
名称 |
描述 |
默认值 |
|---|---|---|
| Content-MD5 | 文件数据校验，设置后BOS会启用文件内容MD5校验，把您提供的MD5与文件的MD5比较，不一致会抛出错误 | 无 |
| Content-Type | 文件的MIME，定义文件的类型及网页编码，决定浏览器将以什么形式、什么编码读取文件。如没有指定，BOS则根据文件的扩展名自动生成，如文件没有扩展名则填默认值 | application/octet-stream |
| Content-Disposition | 指示回复的内容该以何种形式展示，是以内联的形式（即网页或者页面的一部分），还是以包含文件名的附件的形式下载并保存到本地 | 无 |
| Content-Length | 上传的文件的长度，超过流/文件的长度会截断，不足为实际值 | 流/文件时间长度 |
| Expires | 缓存过期时间 | 无 |
| Cache-Control | 指定该Object被下载时的网页的缓存行为 | 指定该Object被下载时网页的缓存行为。取值如下： no-cache：不可直接使用缓存，而是先到服务端验证Object是否已更新。如果Object已更新，表明缓存已过期，需从服务端重新下载Object；如果Object未更新，表明缓存未过期，此时将使用本地缓存。 no-store：所有内容都不会被缓存。 public：所有内容都将被缓存。 private：所有内容只在客户端缓存。 max-age= 默认值：无 |
参考代码如下：
1$options = array(
2 BosOptions::CONTENT_TYPE=>"text/plain",
3 BosOptions::CONTENT_MD5=>"md5",
4 BosOptions::CONTENT_LENGTH=>10,
5 BosOptions::CACHE_CONTROL=>" max-age=86400",
6 );
7
8$client->putObject($bucketName, $objectKey, $data, $options);用户自定义元信息
BOS支持用户自定义元数据来对Object进行描述。如下代码所示：
1$user_meta = array("x-bce-meta-key1" => "value1");
2$client->putObject($bucketName,
3 $objectKey,
4 $data,
5 array(
6 'userMetadata' => $user_meta,
7));提示：
- 在上面代码中，用户自定义了一个名字为”x-bce-meta-key1”，值为”value1”的元数据
- 当用户下载此Object的时候，此元数据也可以一并得到
- 一个Object可以有多个类似的参数，但所有的User Meta总大小不能超过2KB
上传Object时设置存储类型
BOS支持标准存储, 低频存储和冷存储，上传Object并存储为低频存储类型通过指定StorageClass实现，三种存储类型对应的参数如下：
存储类型 |
参数 |
|---|---|
| 标准存储 | STANDARD |
| 低频存储 | STANDARD_IA |
| 冷存储 | COLD |
以低频存储为例，代码如下：
1use BaiduBce\Services\Bos\StorageClass;
2
3// 设置object的storage class为`StorageClass::STANDARD_IA`后，将上传一个低频object（默认为标准object）
4$options = array(
5 BosOptions::STORAGE_CLASS => StorageClass::STANDARD_IA,
6);
7$response = $bos_client->putObjectFromString($bucket, $object, "test", $options);putObject请求处理成功后，BOS会在Header中返回Object的Content-MD5，用户可以根据这个参数来对文件进行校验。
追加上传
上文介绍的简单上传方式，创建的Object都是Normal类型，用户不可再进行追加写，这在日志、视频监控、视频直播等数据复写较频繁的场景中使用不方便。
正因如此，百度智能云BOS特别支持了AppendObject，即以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object，可以对该Object追加数据。AppendObject大小限制为0~5G。
通过AppendObject方式上传示例代码如下：
1// 从文件上传appendable object
2file_put_contents($filename, "test of put append object");
3$response = $client->appendObjectFromFile($bucket, $appendKey, $filename, 0);
4
5// 下次追加写的位置
6$nextOffset = $response->metadata[BosOptions::NEXT_APPEND_OFFSET];
7
8// 从字符串上传appendable object
9$response = $client->appendObjectFromString($bucket, $appendKey, "appendStr", intval($nextOffset));分块上传
除了通过简单上传几追加上传方式将文上传件到BOS以外，BOS还提供了另外一种上传模式 —— Multipart Upload。用户可以在如下的应用场景内（但不仅限于此），使用Multipart Upload上传模式，如：
- 需要支持断点上传。
- 上传超过5GB大小的文件。
- 网络条件较差，和BOS的服务器之间的连接经常断开。
- 需要流式地上传文件。
- 上传文件之前，无法确定上传文件的大小。
下面将一步步介绍Multipart Upload的实现。假设有一个文件，本地路径为 /path/to/file.zip ，由于文件比较大，将其分块传输到BOS中。
初始化Multipart Upload
使用 initiateMultipartUpload 方法来初始化一个分块上传事件：
1$response = $client->initiateMultipartUpload($bucketName, $objectKey);
2$uploadId =$response->uploadId;initiateMultipartUpload 的返回结果中含有 UploadId ，它是区分分块上传事件的唯一标识，在后面的操作中，我们将用到它。
上传低频存储类型Object的初始化
初始化低频存储的一个分块上传事件：
1use BaiduBce\Services\Bos\StorageClass;
2
3$options = array(
4 BosOptions::STORAGE_CLASS => StorageClass::STANDARD_IA,
5);
6$bos_client->initiateMultipartUpload($bucketName, $objectName, $options);上传冷存储类型Object的初始化
初始化冷存储的一个分块上传事件：
1use BaiduBce\Services\Bos\StorageClass;
2
3$options = array(
4 BosOptions::STORAGE_CLASS => StorageClass::COLD,
5);
6$bos_client->initiateMultipartUpload($bucketName, $objectName,$options);上传分块
接着，把文件分块上传。
1// 设置本地需分块上传的文件
2$fileName = "myfilename";
3$fileSize = filesize($fileName);
4//设置分块的开始偏移位置
5$offset = 0;
6$partNumber = 1;
7//设置每块为5MB
8$partSize = 5 * 1024 * 1024;
9$length = $partSize;
10$partList = array();
11$bytesLeft = $fileSize;
12
13//分块上传
14while ($bytesLeft > 0) {
15 $length = ($length > $bytesLeft) ? $bytesLeft : $length;
16 $response = $client->uploadPartFromFile($bucketName, $objectKey, $uploadId, $partNumber, $fileName, $offset, $length);
17 array_push($partList, array("partNumber"=>$partNumber, "eTag"=>$response->metadata["etag"]));
18 $offset += $length;
19 $partNumber++;
20 $bytesLeft -= $length;
21}上面代码的核心是调用 UploadPart 方法来上传每一个分块，但是要注意以下几点：
- UploadPart 方法要求除最后一个Part以外，其他的Part大小都要大于等于5MB。但是Upload Part接口并不会立即校验上传Part的大小；只有当Complete Multipart Upload的时候才会校验。
- 为了保证数据在网络传输过程中不出现错误，建议您在
UploadPart后，使用每个分块BOS返回的Content-MD5值分别验证已上传分块数据的正确性。当所有分块数据合成一个Object后，不再含MD5值。 - Part号码的范围是1~10000。如果超出这个范围，BOS将返回InvalidArgument的错误码。
- 每次上传Part时都要把流定位到此次上传块开头所对应的位置。
- 每次上传Part之后，BOS的返回结果会包含
eTag和partNumber，需要保存到$partList中。$partList类型是list里面每个元素是个dict，每个dict包含两个关键字，一个是partNumber, 一个是eTag；在后续完成分块上传的步骤中会用到它。
完成分块上传
如下代码所示，完成分块上传：
1$response = $client->completeMultipartUpload($bucketName, $objectKey, $uploadId, $partList);
2print $response->location;上面代码中的 partList 是第二步中保存的part列表，BOS收到用户提交的Part列表后，会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后，BOS将把这些数据part组合成一个完整的Object。
取消分块上传
用户可以使用abortMultipartUpload方法取消分块上传。
1$client->abortMultipartUpload($bucketName, $objectKey, $uploadId);获取未完成的分块上传事件
用户可以使用listMultipartUploads方法获取Bucket中未完成的分块上传事件。
1$response = $client->listMultipartUploads($bucketName);
2print $response->bucket;
3print $response->uploads[0]->key;注意：
- 默认情况下，如果Bucket中的分块上传事件的数目大于1000，则只会返回1000个Object，并且返回结果中IsTruncated的值为True，同时返回NextKeyMarker作为下次读取的起点。
- 若想返回更多分块上传事件的数目，可以使用KeyMarker参数分次读取。
大文件上传
BOS PHP SDK 提供针对大文件的分块上传封装接口putSuperObjectFromFile，接口内部会对文件进行分块上传，默认分块大小为5MB，可以指定PART_SIZE。
1$filename = "/home/file.zip";
2$userMeta = array("private" => "private data");
3$options = array(
4 BosOptions::USER_METADATA => $userMeta
5);
6$client->putSuperObjectFromFile($bucket, $object, $filename, $options);获取所有已上传的块信息
用户可以使用listParts方法获取某个上传事件中所有已上传的块：
1$response = $client->listParts($bucketName, $objectKey, $uploadId);
2print $response->bucket;
3print $response->uploads[0]->key;注意：
- 默认情况下，如果Bucket中的分块上传事件的数目大于1000，则只会返回1000个Object，并且返回结果中IsTruncated的值为True，同时返回NextPartNumberMarker作为下次读取的起点。
- 若想返回更多分块上传事件的数目，可以使用PartNumberMarker参数分次读取。
断点续传上传
当用户向BOS上传大文件时，如果网络不稳定或者遇到程序崩等情况，则整个上传就失败了，失败前已经上传的部分也作废，用户不得不重头再来。这样做不仅浪费资源，在网络不稳定的情况下，往往重试多次还是无法完成上传。 基于上述场景，BOS提供了断点续传上传的能力:
- 当网络情况一般的情况下，建议使用三步上传方式，将object分为5Mb的块，参考分块上传。
- 当您的网络情况非常差，推荐使用appendObject的方式进行断点续传，每次append 较小数据256kb，参考追加上传。
提示
- 断点续传是分片上传的封装和加强，是用分片上传实现的；
- 文件较大或网络环境较差时，推荐使用分片上传；
下载文件
BOS PHP SDK提供了丰富的文件下载接口，用户可以通过以下方式从BOS中下载文件：
- 简单流式下载
- 下载到本地文件
- 断点续传下载
- 范围下载
简单流式下载
用户可以通过如下代码将Object读取到一个流中：
1$client->getObjectAsString($bucketName, $objectKey);直接下载Object到文件
用户可以参考如下代码将Object下载到指定文件：
1$client->getObjectToFile($bucketName, $objectKey, $fileName);范围下载
为了实现更多的功能，可以通过使用options配置RANGE参数来指定下载范围，实现更精细化地获取Object。如果指定的下载范围是0 - 100，则返回第0到第100个字节的数据，包括第100个，共101字节的数据，即[0, 100]。RANGE参数的格式为array($offset, $endset)其中两个变量为长整型，单位为字节。用户也可以用此功能实现文件的分段下载和断点续传。
1$options = array(
2 BosOptions::RANGE=>array(0,100),
3);
4$client->getObjectToFile($bucketName, $objectKey, $fileName, $options);其他使用方法
获取Object的存储类型
Object的storage class属性分为STANDARD(标准存储), STANDARD_IA(低频存储)和COLD(冷存储)，通过如下代码可以实现：
1$response = $client->getObjectMetadata($bucketName, $objectKey);
2echo $response[BosOptions::STORAGE_CLASS];只获取ObjectMetadata
用户也可通过 getObjectMetadata 方法可以只获取ObjectMetadata而不获取Object的实体。如下代码所示：
1$response = $client->getObjectMetadata($bucketName, $objectKey);
2echo $response[BosOptions::ETAG];getObjectMetadata方法返回的解析类中可供调用的参数有：
参数 |
说明 |
|---|---|
| contentType | Object的类型 |
| contentLength | Object的大小 |
| contentMd5 | Object的MD5 |
| etag | Object的HTTP协议实体标签 |
| storageClass | Object的存储类型 |
| userMetadata | 如果在PutObject指定了userMetadata自定义meta，则返回此项 |
变更文件存储等级
上文中已提到，BOS支持为文件赋予STANDARD(标准存储), STANDARD_IA(低频存储)和COLD(冷存储)三种存储类型。同时，BOS PHP SDK也支持用户对特定文件执行存储类型变更的操作。
涉及到的参数如下：
参数 |
说明 |
|---|---|
| x-bce-storage-class | 指定Object的存储类型，STANDARD_IA代表低频存储，COLD代表冷存储，不指定时默认是标准存储类型。 |
示例如下：
1use BaiduBce\Services\Bos\StorageClass;
2
3$options = array(
4 BosOptions::STORAGE_CLASS => StorageClass::STANDARD_IA,
5);
6
7// 标准存储转低频存储
8$client->copyObject($bucket, $key, $bucket, $key, $options);
9$response = $client->getObjectMetadata($bucket, $key);
10echo $response[BosOptions::STORAGE_CLASS];
11
12$options = array(
13 BosOptions::STORAGE_CLASS => StorageClass::COLD,
14);
15
16// 低频存储转冷存储
17$client->copyObject($bucket, $key, $bucket, $key, $options);
18$response = $client->getObjectMetadata($bucket, $key);
19echo $response[BosOptions::STORAGE_CLASS];获取文件下载URL
用户可以参考如下代码获取Object的URL：
1use BaiduBce\Services\Bos\BosClient;
2use BaiduBce\Services\Bos\BosOptions;
3use BaiduBce\Auth\signOptions;
4
5$client = new BoSClient($BOS_CONFIG);
6
7$signOptions = array(
8 SignOptions::TIMESTAMP=>new \DateTime(),
9 SignOptions::EXPIRATION_IN_SECONDS=>300,
10);
11$url = $client->generatePreSignedUrl($bucket,
12 $key,
13 array(BosOptions::SIGN_OPTIONS => $signOptions)
14 );说明：
- 用户在调用该函数前，需要手动设置endpoint为所属区域域名。百度智能云目前开放了多区域支持，请参考区域选择说明。目前支持“华北-北京”、“华南-广州”和“华东-苏州”三个区域。北京区域：
http://bj.bcebos.com，广州区域：http://gz.bcebos.com，苏州区域：http://su.bcebos.com。EXPIRATION_IN_SECONDS为指定的URL有效时长，时间从当前时间算起，为可选参数，不配置时系统默认值为1800秒。如果要设置为永久不失效的时间，可以将expirationInSeconds参数设置为 -1，不可设置为其他负数。TIMESTAMP为可选参数，不配置时，系统默认TIMESTAMP为当前时间。- 如果预期获取的文件时公共可读的，则对应URL链接可通过简单规则快速拼接获取:
http://$bucket.$region.bcebos.com/$object或者http://$region.bcebos.com/$bucket/$object。
现已支持通过STS方式获取，配置STS访问BOS见初始化页面，代码示例如下：
1$signOptions = array(
2 SignOptions::TIMESTAMP=>new \DateTime(),
3 SignOptions::EXPIRATION_IN_SECONDS=>1800,
4
5);
6$url = $client->generatePreSignedUrl($bucket,
7 $key,
8 array(BosOptions::SIGN_OPTIONS => $signOptions, BosOptions::PARAMS => array('x-bce-security-token' => $sessionToken))
9 );
10echo $url;列举存储空间中的文件
BOS SDK支持用户通过以下两种方式列举出object：
- 简单列举
- 通过参数复杂列举
除此之外，用户还可在列出文件的同时模拟文件夹
简单列举
当用户希望简单快速列举出所需的文件时，可通过listObjects方法获取Bucket中的Object列表。
1$client->listObjects($bucketName);注意：
- 默认情况下，如果Bucket中的Object数量大于1000，则只会返回1000个Object。
- 若想增大返回Object的数目，可以使用Marker参数分次读取。
通过参数复杂列举
除上述简单列举外，用户还可通过options配置可选参数来实现各种灵活的查询功能。可设置的参数如下：
参数 |
功能 |
|
|---|---|---|
| PREFIX | 限定返回的object key必须以prefix作为前缀 | setPrefix(String prefix) |
| DELIMITER | 是一个用于对Object名字进行分组的字符所有名字包含指定的前缀且第一次出现。Delimiter字符之间的Object作为一组元素: CommonPrefixes | |
| MARKER | 设定结果从marker之后按字母排序的第一个开始返回 | |
| MAX_KEYS | 限定此次返回object的最大数，最大为1000，默认值是1000。如果指定的值大于1000，按1000操作 |
注意：
- 如果有Object以Prefix命名，当仅使用Prefix查询时，返回的所有Key中仍会包含以Prefix命名的Object，详见递归列出目录下所有文件。
- 如果有Object以Prefix命名，当使用Prefix和Delimiter组合查询时，返回的所有Key中会有Null，Key的名字不包含Prefix前缀，详见查看目录下的文件和子目录。
下面我们分别以几个案例说明通过参数列举的方法：
指定最大返回条数
1// 指定最大返回条数为500
2$options = array(
3 BosOptions::MAX_KEYS=>500,
4);
5
6$response = $client->listObjects($bucket, $options);返回指定前缀的object
1// 指定返回前缀为usr的object
2$options = array(
3 BosOptions::PREFIX=>"usr",
4);
5
6$response = $client->listObjects($bucket, $options);从指定Object后返回
1// 用户可以定义不包括某object，从其之后开始返回
2$options = array(
3 BosOptions::MARKER=>"object",
4);
5
6$response = $client->listObjects($bucket, $options);分页获取所有Object
用户可设置每页最多500条记录
1$options = array(
2 BosOptions::MAX_KEYS => 500,
3);
4
5$isTruncated = true;
6while($isTruncated) {
7 $res = $client->listObjects($bucket, $options);
8 $isTruncated = $res->isTruncated;
9 if (property_exists($res, 'nextMarker')) {
10 $options[BosOptions::MARKER] = $res->nextMarker;
11 }
12}分页获取所有特定Object后的结果
用户可设置每页最多500条记录，并从某特定object之后开始获取
1$options = array(
2 BosOptions::MAX_KEYS => 500,
3 BosOptions::MARKER => "object",
4);
5
6$isTruncated = true;
7while($isTruncated) {
8 $res = $client->listObjects($bucket, $options);
9 $isTruncated = $res->isTruncated;
10 if (property_exists($res, 'nextMarker')) {
11 $options[BosOptions::MARKER] = $res->nextMarker;
12 }
13}listObjects方法返回的解析类中可供调用的参数有：
参数 |
说明 |
|---|---|
| name | Bucket名称 |
| prefix | 匹配以prefix开始到第一次出现Delimiter字符之间的object作为一组元素返回 |
| marker | 本次查询的起点 |
| maxKeys | 请求返回的最大数目 |
| isTruncated | 指明是否所有查询都返回了；false-本次已经返回所有结果，true-本次还没有返回所有结果 |
| contents | 返回的一个Object的容器 |
| +key | Object名称 |
| +lastModified | 此Object最后一次被修改的时间 |
| +eTag | Object的HTTP协议实体标签 |
| +storageClass | Object的存储形态 |
| +size | Object的内容的大小（字节数） |
| +owner | Object对应Bucket所属用户信息 |
| ++id | Bucket Owner的用户ID |
| ++displayName | Bucket Owner的名称 |
模拟文件夹功能
在BOS的存储结果中是没有文件夹这个概念的，所有元素都是以Object来存储，但BOS的用户在使用数据时往往需要以文件夹来管理文件。
因此，BOS提供了创建模拟文件夹的能力，其本质上来说是创建了一个size为0的Object。对于这个Object可以上传下载，只是控制台会对以”/“结尾的Object以文件夹的方式展示。
用户可以通过 Delimiter 和 Prefix 参数的配合模拟出文件夹功能。Delimiter 和 Prefix 的组合效果是这样的：
如果把 Prefix 设为某个文件夹名，就可以罗列以此 Prefix 开头的文件，即该文件夹下递归的所有的文件和子文件夹（目录）。文件名在Contents中显示。
如果再把 Delimiter 设置为 “/” 时，返回值就只罗列该文件夹下的文件和子文件夹（目录），该文件夹下的子文件名（目录）返回在 CommonPrefixes 部分，子文件夹下递归的文件和文件夹不被显示。
如下是几个应用方式：
列出Bucket内所有文件
当用户需要获取Bucket下的所有文件时，可以参考分页获取所有Object
递归列出目录下所有文件
可以通过设置 Prefix 参数来获取dir目录下所有的文件：
1$options = array(
2 BosOptions::PREFIX => "dir/",
3);
4
5$isTruncated = true;
6while($isTruncated) {
7 $res = $client->listObjects($bucket, $options);
8 $isTruncated = $res->isTruncated;
9 if (property_exists($res, 'nextMarker')) {
10 $list_options[BosOptions::MARKER] = $res->nextMarker;
11 }
12}查看目录下的文件和子目录
在 Prefix 和 Delimiter 结合的情况下，可以列出dir目录下的文件和子目录：
1$options = array(
2 BosOptions::PREFIX => "dir/",
3 BosOptions::DELIMITER => "/",
4);
5
6$isTruncated = true;
7while($isTruncated) {
8 $res = $client->listObjects($bucket, $options);
9 $isTruncated = $res->isTruncated;
10 if (property_exists($res, 'nextMarker')) {
11 $list_options[BosOptions::MARKER] = $res->nextMarker;
12 }
13}列举Bucket中object的存储属性
当用户完成上传后，如果需要查看指定Bucket中的全部Object的storage class属性，可以通过如下代码实现：
1use BaiduBce\Services\Bos\StorageClass;
2
3$response = $bos_client->listObjects($bucketName);
4$objectList = $response->contents;
5for ($i= 0;$i< count($objectList); $i++){
6 echo $objectList[$i]->storageClass;
7}取回object
用户将文件归档后，可以将文件取回，要求文件处于冰冻状态才能取回
1$client->restoreObject($bucket, $archiveKey, $archiveDay);Object权限控制
设置Object的访问权限
如下代码将Object的权限设置为了private：
1$canned_acl = array("x-bce-acl" => "private");
2$client->setObjectCannedAcl($bucket, $key, $canned_acl);其中CannedAcl.php中封装了三个参数：ACL_PRIVATE、ACL_PUBLIC_READ、ACL_PUBLIC_READ_WRITE，它们分别对应的相关权限为：private、public-read、public-read-write，Object权限控制目前支持前两种。关于权限的具体内容可以参考《BOS API文档 Object权限控制》。
设置指定用户对Object的访问权限
BOS提供setObjectAcl方法和setObjectCannedAcl方法来实现指定用户Object的访问权限设置，可以参考如下代码实现：
- 通过setObjectCannedAcl的
x-bce-grant-read和x-bce-grant-full-control设置指定用户的访问权限
1$canned_acl = array("x-bce-grant-read" => "id=\"7f34788d02a64a9c98f85600567d98a7\",id=\"7f34788d02a64a9c98f85600567d98a8\"");
2$client->setObjectCannedAcl($bucket, $object, $canned_acl);
3
4$canned_acl = array("x-bce-grant-full-control" => "id=\"7f34788d02a64a9c98f85600567d98a7\",id=\"7f34788d02a64a9c98f85600567d98a8\"");
5$client->setObjectCannedAcl($bucket, $object, $canned_acl);- 通过setObjectAcl设置object访问权限
1$my_acl = array(
2 array(
3 'grantee' => array(
4 array(
5 'id' => '7f34788d02a64a9c98f85600567d98a7',
6 ),
7 array(
8 'id' => 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
9 ),
10 ),
11 'permission' => array('FULL_CONTROL'),
12 ),
13);
14$client->setObjectAcl($bucket, $object, $my_acl);注意：
- permission中的权限设置包含两个值：
READ、FULL_CONTROL，它们分别对应相关权限。- 设置两个以上（含两个）被授权人时，请参考以上示例的格式，若将数组合并会返回报错。
查看Object的权限
如下代码可以查Object的权限：
1$response = $client->getObjectAcl($bucket, $object);getObjectAcl方法返回的解析类中可供调用的参数有：
参数 |
说明 |
|---|---|
| accessControlList | 标识Object的权限列表 |
| grantee | 标识被授权人 |
| -id | 被授权人ID |
| permission | 标识被授权人的权限 |
删除Object的权限
如下代码可以删除Object的权限：
1$response = $client->deleteObjectAcl($bucket, $object);删除文件
删除单个文件
可参考如下代码删除了一个Object:
1$client->deleteObject($bucket, $object);删除多个文件
可参考如下代码删除多个object:
1$deleteattay = array(
2 array(
3 "key"=>$diping_key
4 ),
5 );
6$client->deleteMultipleObjects($bucket, $deleteattay);查看文件是否存在
用户可通过如下操作查看某文件是否存在：
1try {
2 $client->getObjectMetadata($bucket, $object);
3} catch (\BaiduBce\Exception\BceBaseException $e) {
4 if ($e->getStatusCode() == 404) {
5 echo $object . " not exist!";
6 }
7}获取及更新文件元信息
文件元信息(Object Metadata)，是对用户上传BOS的文件的属性描述，分为两种：HTTP标准属性（HTTP Headers）和User Meta（用户自定义元信息）。
获取文件元信息
修改文件元信息
BOS修改Object的Metadata通过拷贝Object实现。即拷贝Object的时候，把目的Bucket设置为源Bucket，目的Object设置为源Object，并设置新的Metadata，通过拷贝自身实现修改Metadata的目的。如果不设置新的Metadata，则报错。
1$userMeta = array("private" => "newvalue");
2$contentType ="text/plain"
3$options = array(
4 BosOptions::USER_METADATA => $userMeta,
5 BosOptions::CONTENT_TYPE=>$contentType
6);
7
8$client->copyObject($bucket, $key, $bucket, $key,$options);
9$response = $client->getObjectMetadata($bucket, $key);
10echo $response['userMetadata']['private']拷贝Object
拷贝一个文件
用户可以通过copyObject方法拷贝一个Object，如下代码所示：
1$client->copyObject($sourceBucketName, $sourceObjectKey, $targetBucketName, $targetObjectKey);copyObject方法可以通过options配置可选参数，参数列表参考如下:
参数 |
说明 |
|---|---|
| USER_METADATA | 用户自定义Meta，包含Key-Value对 |
| ETAG | Source Object的Etag，若选择上传，则会对Target Object和Source Object的Etag进行比对，若不相同，则返回错误。 |
1use BaiduBce\Services\Bos\BosOptions;
2
3$userMeta = array("private" => "private data");
4$options = array(
5 BosOptions::USER_METADATA => $userMeta
6);
7
8$client->copyObject($sourceBucketName, $sourceObjectKey, $targetBucketName, $targetObjectKey, $options);同步Copy
当前BOS的CopyObject接口是通过同步方式实现的。同步方式下，BOS端会等待Copy实际完成才返回成功。同步Copy能帮助用户更准确的判断Copy状态，但用户感知的复制时间会变长，且复制时间和文件大小成正比。
同步Copy方式更符合业界常规，提升了与其它平台的兼容性。同步Copy方式还简化了BOS服务端的业务逻辑，提高了服务效率。
如果您使用bce-php-sdk-0.8.17版本之前的SDK，有可能会出现复制请求成功，但文件实际复制失败的情况，所以建议您使用最新版本SDK。
分块拷贝
除了通过CopyObject接⼝拷贝文件以外，BOS还提供了另外一种拷贝模式——Multipart Upload Copy。用户可以在如下的应用场景内（但不仅限于此），使用Multipart Upload Copy，如：
- 需要支持断点拷贝。
- 拷贝超过5GB大小的文件。
- 网络条件较差，和BOS的服务器之间的连接经常断开。
下面将介绍分步实现三步拷贝。
三步拷贝包含init、“拷贝分块”和complete三步，其中init和complete的操作同分块上传一致，可直接参考初始化Multipart Upload和完成分块上传。
1$partNumber = 1;
2$offSet = 0;
3
4//设置每块为5MB
5$partSize = 5 * 1024 * 1024;
6$length = $partSize;
7$partList = array();
8$bytesLeft = $client->getObjectMetadata($sourceBucketName, $sourceKey)["contentLength"];
9
10//分块上传
11while ($bytesLeft > 0) {
12 $length = ($length > $bytesLeft) ? $bytesLeft : $length;
13 $options = array(
14 BosOptions::RANGE => array($offSet, $offSet + $length - 1)
15 );
16 $response = $client->uploadPartCopy($sourceBucketName, $sourceKey, $targetBucketName, $targetKey, $uploadId, $partNumber, $options);
17 array_push($partList, array("partNumber"=>$partNumber, "eTag"=>$response->eTag));
18 $partNumber++;
19 $bytesLeft -= $length;
20 $offSet += $length;
21}注意: size参数以字节为单位，定义每个分块的大小，除最后一个Part以外，其他的Part大小都要大于5MB。
抓取object
如下代码用于从指定URL抓取资源，并将资源存储到指定的Bucket中。此操作需要请求者对该Bucket有写权限，每次只能抓取一个Object，且用户可以自定义Object的名称，详情可参考FetchObject接口。
1use BaiduBce\Services\Bos\BosOptions;
2
3$options = array(
4 BosOptions::STORAGE_CLASS => "STANDARD",
5 BosOptions::BCE_FETCH_MODE => "async"
6);
7$fetchSource = "dowload_url";
8$client->fetchObject(
9 $bucketName,
10 $objectName,
11 $fetchSource,
12 $options
13 );用户额度
设置用户额度
如下代码用于设置用户额度
1$client->putUserQuota($maxBucketCount, $maxCapacityMegaBytes, $maxObjectCount);获取用户额度
如下代码用于获取用户额度
1$client->getUserQuota();删除用户额度
如下代码用于删除用户额度
1$client->deleteUserQuota();合规保留
初始化合规保留
1$client->initBucketObjectLock($BUCKET_NAME, $retentDays);获取合规保留
1$client->getBucketObjectLock($BUCKET_NAME);删除合规保留
1$client->deleteBucketObjectLock($BUCKET_NAME);延长合规保留
如下代码可以延长保留时间
1$client->extendBucketObjectLock($BUCKET_NAME);事件通知
创建事件通知
如下代码用于创建事件通知
1$mynotification =
2 array(
3 array(
4 'id'=> "water-test-1",
5 'name'=> "water-rule-1",
6 'appId'=> "water-app-id-1",
7 'status'=> "enabled",
8 'resources'=> array("/*.jpg", "/*.png"),
9 'events'=> array("PutObject") ,
10 'apps'=> array(
11 array(
12 'id' => "app-id-1",
13 'eventUrl' => "https://op-log-app-service.chehejia.com/op-log-app-service/v1-0/log/bos/event",
14 'xVars' => "xvars",
15 ),
16 ),
17 ));
18$client->putNotification($bucket, $mynotification);获取事件
如下代码用于获取事件通知
1$getRes = $client->getNotification($bucket);删除事件通知
如下代码用于删除事件
1$client->deleteNotification($bucket);