**桶的管理**
##########################
桶是NOS上的存储空间，也是计费、权限控制、日志记录等高级功能的管理实体。


新建桶
=========================

您可以使用S3Client::createBucket 新建桶::

    <?php
    /**
     * 创建一个桶
     * acl 指的是bucket的访问控制权限，有两种，私有读写，公共读私有写。
     * 私有读写就是只有bucket的拥有者或授权用户才有权限操作
     * 公共读私有写，任意用户可以读，只有授权用户才能写
     *
     * @param S3Client $S3Client S3Client实例
     * @param string    $bucketName 要创建的bucket名字
     * @param string    $Acl,有效的值为private-->write,public-read-->read
     * @return null
     */
    
    function createBucket($s3Client,$bucketName,$Acl){
        try {
            $result = $s3Client->createBucket([
                'Bucket' => $bucketName,
                'ACL' => $Acl
            ]);
        }catch (AwsException $e) {
            // output error message if fails
            echo $e->getMessage() + "\n";
        }
    }	

.. attention::
	1. 桶的命名规范，请参见 `基本概念 桶命名规范 <../api/basicConcept.html#id4>`_
	2. 桶的名字全局唯一，不同用户之间的桶名也不能重复
	3. 关于权限更加详细的说明，请参见: `桶的属性 <../api/basicConcept.html#id6>`_

判断桶是否存在
=========================
您可以使用S3Client::doesBucketExist 判断桶是否存在::

    <?php
   /**
    * 判断桶是否存在
    * @param $s3Client S3Client实例
    * @param $bucketName 桶名
    */
        
    function doesBucketExist($s3Client,$bucketName){
        try{
            $res = $s3Client->doesBucketExist($bucketName);
        } catch (\Aws\Exception\AwsException $e){
            echo $e->getMessage() + "\n";
        }
        if ($res === true) {
            print(__FUNCTION__ . ": OK" . "\n");
        } else {
            print(__FUNCTION__ . ": FAILED" . "\n");
        }
    }

列出用户所有的桶
========================
您可以使用S3Client::listBuckets 列出当前用户所有的桶::

    <?php
    /**
    * 列出当前用户所有的桶
    * @param $s3Client S3Client实例
    */
    function listBuckets($s3Client){
        $buckets = $s3Client->listBuckets();
        foreach ($buckets['Buckets'] as $bucket){
            echo $bucket['Name']."\n";
        }
    }

删除桶
=======================
您可以使用S3Client::deleteBucket 删除空桶::

    <?php
    /**
    * 根据给定的桶名删除桶
    * @param $s3Client S3Client实例
    * @param $bucketName 桶名
    */
    function deleteBucket($s3Client,$bucketName){
        try {
            $deleteResult = $s3Client->deleteBucket(['Bucket' => $bucketName]);
            echo $deleteResult;
        } catch (Exception $exception){
            echo $exception->getMessage() . "\n";
        }
    }

.. attention::

    1. 如果存储空间不为空（存储空间中有文件或者分片上传的分片），则存储空间无法删除；
    2. 必须先删除存储空间中的所有文件和分片后，存储空间才能成功删除。

设置桶的ACL属性
======================
除了在创建桶的时候可以指定桶的ACL属性之外，也可以根据自己的业务需求对桶的ACL进行修改，这个操作只有桶的拥有者有权限修改，关于桶的权限修改请参考: `桶的属性修改 <../管理存储空间.html#acl>`_ 

桶存在两种权限:

======================== ====================================================
权限                         备注                                           
======================== ====================================================
私有读写                  'private'                                        
公共读私有写               'public-read'                                    
======================== ====================================================

您可以使用S3Client::putBucketAcl设置桶的访问权限::

    <?php
    /**
    * 设置桶的Acl
    * @param $s3Client S3Client实例
    * @param $bucketName 桶名
    * @param $Acl 有效的值为private,public-read
    */
    function putBucketAcl($s3Client,$bucketName,$Acl){
        try{
            $s3Client->putBucketAcl(array(
                'ACL' => $Acl,
                'Bucket' => $bucketName,));
        } catch (\Aws\Exception\AwsException $exception){
            echo $exception->getMessage();
        }

    }

获取桶的ACL属性
=======================
您可以使用S3Client::getBucketAcl获取桶的访问权限::

    <?php
    /**
    * 获取桶的Acl
    * @param $s3Client S3Client实例
    * @param $bucketName 桶名
    */
    function getBucketAcl($s3Client,$bucketName){
        try{
            $result = $s3Client->getBucketAcl(['Bucket'=>$bucketName]);
            echo $result;
        } catch (\Aws\Exception\AwsException $e){
            echo $e->getMessage() + "\n";
        }

    }