创建桶

功能说明

桶（Bucket）是用于存储对象（Object）的容器，所有的对象都必须隶属于某个桶。您可以使用 createBucket 接口创建桶。

代码示例

public function CreateBucket()
{
    try {
        $res = $this->s3Client->createBucket([
            'Bucket' => '<your-bucket-name>',
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是

获取桶列表

功能说明

桶（Bucket）是用于存储对象（Object）的容器，所有的对象都必须隶属于某个桶。您可以通过listBuckets接口获取桶列表信息。

代码示例

public function ListBucket()
{
    try {
        $res = $this->s3Client->listBuckets();
        var_dump($res->get('Buckets'));
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

返回结果

参数	类型	说明
Buckets	Bucket array	桶信息列表

判断桶是否存在

功能说明

桶（Bucket）是用于存储对象（Object）的容器，所有的对象都必须隶属于某个桶。您可以使用 doesBucketExist 接口判断桶是否存在。

代码示例

public function DoesBucketExist()
{
    $bucket = '<your-bucket-name>';
    try {
        $exist = $this->s3Client->doesBucketExist($bucket);
        echo $exist;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
exist	bool	桶是否存在

删除桶

功能说明

桶（Bucket）是用于存储对象（Object）的容器，所有的对象都必须隶属于某个桶。您可以通过 deleteBucket 接口删除桶。删除一个桶前，需要先删除该桶中的全部对象（包括对象版本）。

代码示例

public function DeleteBucket()
{
    try {
        $res = $this->s3Client->deleteBucket([
            'Bucket' => '<your-bucket-name>',
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是

设置桶访问权限

功能说明

您可以使用putBucketAcl接口进行桶访问权限的修改。用户在设置 bucket 的 ACL 之前需要具备 WRITE_ACP 权限。桶访问权限包含了 AccessControlList 与CannedAccesssControlList 两种格式。

代码示例

CannedAccesssControlList

使用 CannedAccesssControlList 设置桶的访问权限示例代码如下:

public function PutBucketAcl()
{
    //设置桶为公共读写
    try {
        $this->s3Client->putBucketAcl([
            'Bucket' => '<your-bucket-name>',
            'ACL' => 'public-read', // private、public-read、public-read-write
        ]);
        echo "Succeed in setting bucket ACL.\n";
    } catch (AwsException $e) {
        // Display error message
        echo $e->getMessage();
        echo "\n";
    }
    echo "putBucketAcl success\n";
}

AccessControlList

使用 AccessControlList 设置桶访问权限时，可以设置特定用户对桶的访问权限。

public function PutBucketAcl2()
{
    try {
        $this->s3Client->putBucketAcl([
            'Bucket' => '<your-bucket-name>',
            'AccessControlPolicy' => [
                // 可以从 getBucketAcl 接口获取 Owner 信息
                'Owner' => [
                    'ID' => 'exampleuser',
                    'DisplayName' => 'Example DisplayName',
                ],
                'Grants' => [
                    [
                        //开启用户 <your-user-id> 的完全控制权限
                        'Grantee' => [
                            'ID' => '<your-user-id>',
                            'Type' => 'CanonicalUser',
                        ],
                        'Permission' => 'FULL_CONTROL', // FULL_CONTROL、WRITE、WRITE_ACP、READ、READ_ACP
                    ],
                    [
                        //开启所有用户的读权限
                        'Grantee' => [
                            'Type' => 'Group',
                            'URI' => 'http://acs.amazonaws.com/groups/global/AllUsers',
                        ],
                        'Permission' => 'READ',
                    ],
                    // ...
                ],
            ],
        ]);
        echo "Succeed in setting bucket ACL.\n";
    } catch (AwsException $e) {
        echo $e->getMessage();
        echo "\n";
    }
}

请求参数

CannedAccesssControlList

使用 CannedAccesssControlList 方式设置桶权限参数如下：

参数	类型	说明	是否必要
Bucket	string	桶名称	是
ACL	string	CannedAccesssControlList 值	是

CannedAccesssControlList 是一系列的预定义访问权限，通过 ACL 参数设置，ACL可设置为以下值：

ACL值	权限
private	私有读写
public-read	公共读私有写
public-read-write	公共读写

AccessControlList

使用 AccessControlList 方式设置桶权限参数如下：

参数	类型	说明	是否必要
Bucket	string	桶名称	是
AccessControlPolicy	AccessControlPolicy	acl详细配置	是

在 AccessControlList 中可通过 Grants 设置权限，Grants 中关于Permission说明如下：

Permission值	权限
READ	允许列出桶中的对象
WRITE	允许创建、覆盖、删除桶中的对象
READ_ACP	允许获取桶的ACL信息
WRITE_ACP	允许修改桶的ACL信息
FULL_CONTROL	获得READ、WRITE、READ_ACP、WRITE_ACP权限

获取桶访问权限

功能说明

您可以使用 getBucketAcl 接口获取桶的访问权限。

代码示例

public function GetBucketAcl()
{
    try {
        $resp = $this->s3Client->getBucketAcl([
            'Bucket' => '<your-bucket-name>'
        ]);
        //打印获取的桶 owner displayname，ID 以及访问权限信息
        echo "Succeed in retrieving bucket ACL as follows: \n";
        echo 'Owner DisplayName: ' . $resp['Owner']['DisplayName'] . "\n";
        echo 'Owner ID: '           . $resp['Owner']['ID']          . "\n";
        foreach ($resp['Grants'] as $grant) {
            echo "Grant: \n";
            foreach($grant['Grantee'] as $k=>$val)
            {
                echo $k . "： " . $val . "\n";
            }
            echo 'Permission: ' . $grant['Permission'] . "\n";
        }
    } catch (AwsException $e) {
        echo 'error:' . $e->getMessage();
        echo "\n";
    }
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
Owner	Owner	桶的owner信息
Grants	Grants	桶的访问权限信息

设置桶策略

功能说明

您可以使用 putBucketPolicy 接口设定桶策略，桶策略可以灵活地配置用户各种操作和访问资源的权限。访问控制列表只能对单一对象设置权限，而桶策略可以基于各种条件对一个桶内的全部或者一组对象配置权限。桶的拥有者拥有 PutBucketPolicy 操作的权限，如果桶已经设置了 policy ，则新设置的 policy 会覆盖原有的policy。

policy的示例如下：

{
    "Id":"PolicyId",
    "Version":"2012-10-17",
    "Statement":[
        {
            "Sid":"ExampleStatementID1",
            "Principal":{
                "AWS":[
                    "arn:aws:iam:::user/userId",
                    "arn:aws:iam:::user/userName"
                ]
            },
            "Effect":"Allow",
            "Action":[
                "s3:ListBucket",
                "s3:CreateBucket"
            ],
            "Resource":[
                "arn:aws:iam:::exampleBucket"
            ],
            "Condition":"some conditions"
        },
        ......
    ]
}

Statement的内容说明如下：

元素	描述	是否必要
Sid	statement Id，可选关键字，描述statement的字符串	否
Principal	可选关键字，被授权人，指定本条statement权限针对的Domain以及User，支持通配符“”，表示所有用户（匿名用户）。当对Domain下所有用户授权时，Principal格式为arn:aws:iam:::user/。当对某个User进行授权时，Principal格式为arn:aws:iam:::user/<your-user-name>	可选，Principal与NotPrincipal选其一
NotPrincipal	可选关键字，不被授权人，statement匹配除此之外的其他人。取值同Principal	可选，NotPrincipal与Principal选其一
Action	可选关键字，指定本条statement作用的操作，Action字段为对象存储支持的所有操作集合，以字符串形式表示，不区分大小写。支持通配符“”，表示该资源能进行的所有操作。例如："Action":["s3:List", "s3:Get*"]	可选，Action与NotAction选其一
NotAction	可选关键字，指定一组操作，statement匹配除该组操作之外的其他操作。取值同Action	可选，NotAction与Action选其一
Effect	必选关键字，指定本条statement的权限是允许还是拒绝，Effect的值必须为Allow或者Deny	必选
Resource	可选关键字，指定statement起作用的一组资源，支持通配符”*”，表示所有资源	可选，Resource与NotResource选其一
NotResource	可选关键字，指定一组资源，statement匹配除该组资源之外的其他资源。取值同Resource	可选，NotResource与Resource选其一
Condition	可选关键字，本条statement生效的条件	可选

代码示例

在上传对象时如果不设置对象访问权限，默认下只有对象的拥有者才能访问该对象。如果需要使桶内对象可公共读，可以通过设置桶策略的方式允许桶内对象公共读，以下代码展示如何设置桶内对象可公共读的策略：

public function PutBucketPolicy()
{
    $bucket = '<your-bucket-name>';
    $this->s3Client->putBucketPolicy([
        'Bucket' => $bucket,
        'Policy' => '{
                "Version": "2012-10-17",
                "Statement": [{
                    "Sid": "1",
                    "Effect": "Allow",
                    "Principal": {"AWS": "*"},
                    "Action": ["s3:GetObject"],
                    "Resource": ["arn:aws:s3:::' . $bucket . '/*"]
                }]
            }',
    ]);
    echo "putBucketPolicy success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
Policy	string	策略内容，json字符串	是

获取桶策略

功能说明

您可以使用 getBucketPolicy 接口获取桶策略。

代码示例

public function GetBucketPolicy()
{
    $res = $this->s3Client->getBucketPolicy([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "getBucketPolicy success " . $res->get('Policy') . "\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
Policy	string	json格式的桶策略

关于桶策略的说明请参考桶策略说明。

删除桶策略

功能说明

您可以使用 deleteBucketPolicy 接口删除桶策略。

代码示例

public function DeleteBucketPolicy()
{
    $this->s3Client->deleteBucketPolicy([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "deleteBucketPolicy success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是

设置桶生命周期配置

功能说明

生命周期管理可以通过设置规则实现自动清理过期的对象，优化存储空间。本文介绍如何设置桶（Bucket）生命周期配置。您可以使用putBucketLifecycleConfiguration接口设置桶的生命周期配置，配置规则可以通过匹配对象key前缀、标签的方法设置当前版本或者历史版本对象的过期时间，对象过期后会被自动删除。

代码示例

public function PutBucketLifecycleConfiguration()
{
    $this->s3Client->putBucketLifecycleConfiguration([
        'Bucket' => '<your-bucket-name>',
        'LifecycleConfiguration' => [
            'Rules' => [
                [
                    'ID' => 'TestOnly', // unique id
                    'Expiration' => [
                        'Days' => 365,
                    ],
                    'Status' => 'Enabled', // required
                    'Filter' => [       // required
                        'Prefix' => '',
                    ],
                    'Transitions' => [
                        [
                            'Days' => 365,
                            'StorageClass' => 'GLACIER',
                        ],
                    ],
                    'AbortIncompleteMultipartUpload' => [
                        'DaysAfterInitiation' => 365,
                    ],
                ],
            ],
        ],
    ]);
    echo "putBucketLifecycleConfiguration success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
LifecycleConfiguration	LifecycleConfiguration	封装了生命周期规则的数组，最多包含1000条规则	是

关于生命周期规则Rule一些说明

参数	类型	说明	是否必要
ID	string	规则ID	否
Status	string	是否启用规则（Enabled\|Disabled）	是
Expiration	Expiration	文件过期时间	否
AbortIncompleteMultipartUpload	AbortIncompleteMultipartUpload	未完成上传的分片过期时间	否
Transitions	Transition数组	文件转换到低频存储规则（距离修改时间）	否
Filter	Filter	应用范围，可以指定前缀或对象标签	否

关于Expiration的说明：

参数	类型	说明
Days	int	过期天数

关于AbortIncompleteMultipartUpload的说明：

参数	类型	说明
DaysAfterInitiation	int	过期天数

关于Transition的说明：

参数	类型	说明
Days	int	转换过期天数
StorageClass	StorageClass	要转换的存储类型

关于Filter的说明：

参数	类型	说明
Prefix	string	需要过滤的前缀

获取桶生命周期配置

功能说明

您可以使用 GetBucketLifecycleConfiguration 接口获取桶的生命周期配置。

代码示例

public function GetBucketLifecycleConfiguration()
{
    $res = $this->s3Client->getBucketLifecycleConfiguration([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "getBucketLifecycleConfiguration success " . $res . "\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
Rules	Rules	一个描述生命周期管理的规则数组，一条规则包含了规则ID、匹配的对象key前缀、匹配的对象标签信息、当前版本对象过期时间、历史版本对象过期时间和是否生效标识等信息

关于生命周期规则Rule一些说明

参数	类型	说明
ID	string	规则ID
Status	string	是否启用规则（Enabled\|Disabled）
Expiration	Expiration	文件过期时间
AbortIncompleteMultipartUpload	AbortIncompleteMultipartUpload	未完成上传的分片过期时间
Transitions	Transition数组	文件转换到低频存储规则（距离修改时间）
Filter	Filter	应用范围，可以指定前缀或对象标签

关于Expiration的说明：

参数	类型	说明
Days	int	过期天数

关于AbortIncompleteMultipartUpload的说明：

参数	类型	说明
DaysAfterInitiation	int	过期天数

关于Transition的说明：

参数	类型	说明
Days	int	转换过期天数
StorageClass	StorageClass	要转换的存储类型

关于Filter的说明：

参数	类型	说明
Prefix	string	需要过滤的前缀

删除桶生命周期配置

功能说明

您可以使用deleteBucketLifecycle接口删除桶的生命周期配置。

代码示例

public function DeleteBucketLifecycleConfiguration()
{
    $this->s3Client->deleteBucketLifecycle([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "deleteBucketLifecycle success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

设置桶跨域访问配置

功能说明

跨域资源共享 (CORS) 定义了在一个域中加载的客户端 Web 应用程序与另一个域中的资源交互的方式。利用 CORS 支持，您可以构建丰富的客户端 Web 应用程序，同时可以选择性地允许跨源访问您的资源。

您可以通过putBucketCors接口设置桶的跨域访问配置。

代码示例

public function PutBucketCors()
{
    $this->s3Client->putBucketCors([
        'Bucket' => '<your-bucket-name>',
        'CORSConfiguration' => [
            'CORSRules' => [
                [
                    'AllowedHeaders' => ["*"],
                    'AllowedMethods' => ["POST", "GET", "PUT", "DELETE", "HEAD"],
                    'AllowedOrigins' => ["*"], // 可以使用http://domain:port
                    'ExposeHeaders' => ["ETag"],
                    'MaxAgeSeconds' => 3600,
                ],
            ],
        ]
    ]);
    echo "putBucketCors success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是
CORSConfiguration	CORSConfiguration	跨域访问规则	是

关于CORSRules一些说明

参数	说明
AllowedMethods	允许的请求方法
AllowedOrigins	允许的请求源
AllowedHeaders	允许的请求头
ExposedHeaders	允许返回的Response Header
MaxAgeSeconds	跨域请求结果的缓存时间

获取桶跨域访问配置

功能说明

您可以通过getBucketCors接口获取桶跨域访问配置。

代码示例

public function GetBucketCors()
{
    $res = $this->s3Client->getBucketCors([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "getBucketCors success " . $res . "\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
CORSRules	CORSRules	跨域访问规则

关于CORSRules一些说明

参数	说明
AllowedMethods	允许的请求方法
AllowedOrigins	允许的请求源
AllowedHeaders	允许的请求头
ExposedHeaders	允许返回的Response Header
MaxAgeSeconds	跨域请求结果的缓存时间

删除桶跨域访问配置

功能说明

您可以通过deleteBucketCors接口删除桶跨域访问配置。

示例代码

public function DeleteBucketCors()
{
    $this->s3Client->deleteBucketCors([
        'Bucket' => '<your-bucket-name>',
    ]);
    echo "deleteBucketCors success\n";
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

设置桶版本控制状态

功能说明

通过媒体存储提供的版本控制，您可以在一个桶中保留多个对象版本。例如，image.jpg(版本1)和image.jpg(版本2)。如果您希望防止自己意外覆盖和删除版本，或存档对象，以便您可以检索早期版本的对象，您可以开启版本控制功能。

开启版本控制
对桶中的所有对象启用版本控制，之后每个添加到桶中的对象都会被设置一个唯一的version id。
暂停版本控制
对桶中的所有对象暂停版本控制，之后每个添加到桶中的对象的version ID会被设置为null。桶开启版本控制功能之后，无法再关闭该功能，只能暂停。

您可以使用 putBucketVersioning 接口开启或暂停版本控制。

代码示例

public function PutBucketVersioning()
{
    //启用版本控制
    $this->s3Client->putBucketVersioning([
        'Bucket' => '<your-bucket-name>',
        'VersioningConfiguration' => [
            'Status' => 'Enabled', //启用版本控制：Enabled，暂停版本控制：Suspended
        ],
    ]);
    echo "putBucketVersioning success\n";
}

请求参数

PutBucketVersioning 的参数说明：

参数	类型	说明	是否必要
Bucket	String	桶名称	是
VersioningConfiguration	VersioningConfiguration	版本控制设置	是

关于 VersioningConfiguration 中 Status 的一些说明

参数	说明
Enabled	开启版本控制
Suspended	暂停版本控制

获取桶版本控制状态

功能说明

您可以使用 getBucketVersioning接口获取版本控制状态。

代码示例

public function GetBucketVersioning()
{
    try {
        $res = $this->s3Client->getBucketVersioning([
            'Bucket' => '<your-bucket-name>',
        ]);
        echo $res;
    } catch (Aws\S3\Exception\S3Exception $e) {
        echo "Exception: $e";
    }
}

请求参数

参数	类型	说明	是否必要
Bucket	string	桶名称	是

返回结果

参数	类型	说明
Status	string	桶是否开启版本控制。若无Status返回，则未开启；如Status为Enabled，则已开启；如Status为Suspended，则已暂停

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

媒体存储

媒体存储

创建桶

功能说明

代码示例

请求参数

获取桶列表

功能说明

代码示例

返回结果

判断桶是否存在

功能说明

代码示例

请求参数

返回结果

删除桶

功能说明

代码示例

请求参数

设置桶访问权限

功能说明

代码示例

请求参数

获取桶访问权限

功能说明

代码示例

请求参数

返回结果

设置桶策略

功能说明

代码示例

请求参数

获取桶策略

功能说明

代码示例

请求参数

返回结果

删除桶策略

功能说明

代码示例

请求参数

设置桶生命周期配置

功能说明

代码示例

请求参数

获取桶生命周期配置

功能说明

代码示例

请求参数

返回结果

删除桶生命周期配置

功能说明

代码示例

请求参数

设置桶跨域访问配置

功能说明

代码示例

请求参数

获取桶跨域访问配置

功能说明

代码示例

请求参数

返回结果

删除桶跨域访问配置

功能说明

示例代码

请求参数

设置桶版本控制状态

功能说明

代码示例

请求参数

获取桶版本控制状态