创建桶

功能说明

您可以使用 createBucket 接口创建桶，创建桶时可以指定桶的名称、访问权限和区域位置等。

代码示例

// Create the parameters for calling createBucket
var bucketParams = {
    Bucket: "<your-bucket-name>",
    ACL: 'private',
    CreateBucketConfiguration: {
        LocationConstraint: ''
    }
};

// call S3 to create the bucket
s3Client.createBucket(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
ACL	String	设置桶访问权限为私有读写	否
CreateBucketConfiguration	Object	创建桶的基本配置	是
LocationConstraint	String	设置桶区域位置	是

返回结果

根据返回码判断是否操作成功。

获取桶列表

功能说明

您可以使用 listBuckets 接口获取桶列表，以下代码展示如何获取桶列表。

代码示例

// Call s3Client to list the buckets
s3Client.listBuckets(function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data.Buckets);
    }
});

请求参数

无

返回结果

参数	类型	说明
Buckets	Array	桶列表
Owner	Object	bucket的拥有者信息

关于Buckets一些说明

参数	说明
Name	桶名
CreationDate	桶创建时间

判断桶是否存在

功能说明

您可以使用 headBucket接口判断桶是否存在，以下代码展示如何判断一个桶是否存在。

代码示例

var params = {
    Bucket: "<your-bucket-name>",
}
s3Client.headBucket(params, function (err, data) {
    if (err) {
        console.log(err);
    } else {
        console.log(data);
    }
})

请求参数

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

返回结果

根据返回码判断是否操作成功。

删除桶

功能说明

您可以使用 deleteBucket接口刪除桶，以下代码展示如何刪除桶。注意：在删除桶前，必须先确保桶为空，否则会导致BucketNotEmpty错误。

代码示例

// Create params for s3Client.deleteBucket
var bucketParams = {
    Bucket: "<your-bucket-name>",
};

// Call s3Client to delete the bucket
s3Client.deleteBucket(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

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

返回结果

根据返回码判断是否操作成功。

设置桶访问权限

功能说明

您可以使用setBucketAcl接口设置桶的访问权限(ACL) ，以下代码展示如何设置桶的访问权限。

使用访问控制列表（ACL）在存储桶上设置桶访问权限。要设置存储桶的ACL，您必须具有WRITE_ACP权限。您可以使用以下两种方式之一来设置存储桶的权限：在请求正文中指定ACL、使用请求标头指定权限。注意：您不能同时使用正文和请求标头指定访问权限。

xos支持一组预定义的ACL，称为canned ACL。每个canned ACL都有一组预定义的被许可人和权限，预定义的访问策略使用请求标头指定权限，见下表：

权限	描述	SDK对应值
私有读写	所有者获得FULL_CONTROL。其他人没有访问权限（默认）	private
公共读私有写	所有者获得FULL_CONTROL。 AllUsers组获得READ访问权限	public-read
公共读写	所有者获得FULL_CONTROL。 AllUsers组具有“读取”和“写入”访问权限。通常不建议在存储桶上授予此权限	public-read-write

指定显式访问权限和被授权用户。这些参数映射到s3Client在ACL中支持的权限集。使用 AccessControlList 设置桶访问权限时，可以设置特定用户对桶的访问权限。桶的 AccessControlList 权限如下表：

权限	SDK对应值
可读，可列出桶下的对象。	READ
可写，可创建/删除/覆盖写该桶下的对象。	WRITE
可读取桶的acl规则。	READ_ACP
可修改桶的acl规则。	WRITE_ACP
完全权限。拥有以上所有权限。	FULL_CONTROL

代码示例

使用canned ACL设置桶的访问权限示例代码如下：用预定义访问策略设置桶权限。

s3Client.putBucketAcl({
    Bucket: "<your-bucket-name>",
    // 设置桶访问权限
    ACL: private | public-read | public-read-write,
}, (err, data) => {
    if (err) {
        console.error(err);
    } else {
        console.log(data);
    }
});

使用AccesssControlList设置桶的访问权限示例代码如下：以下示例替换了存储桶上的现有ACL。授予存储桶所有者（使用所有者ID指定）FullControl权限，并向用户组授予写入权限。

var params = {
    Bucket: "<your-bucket-name>",
    AccessControlPolicy: {
        Grants: [
            {
                Grantee: {
                    // The canonical ID of the user. This ID is an obfuscated form of your XOS account number.
                    ID: "<grantee-canonical-id>",
                    Type: "CanonicalUser",
                },
                Permission: "FULL_CONTROL",
            },
        ],
        Owner: {
            ID: "<owner-canonical-id>",
        },
    }};
s3Client.putBucketAcl(params, function (err, data) {
    if (err) {
        console.error(err);
    } else {
        console.log(data);
    }
});

请求参数

预定义的ACL

参数	类型	说明	是否必要
Bucket	String	桶名称	是
ACL	String	桶访问权限，参考上面的canned ACL	是

指定显式访问权限和被授权用户AccessControlList

参数	类型	说明	是否必要
Bucket	String	桶名称	是
AccessControlPolicy	Object	访问权限和被授权用户对象	是

关于AccessControlPolicy的说明：

Owner参数用来指定桶的所有者信息，Grants参数用来指定被授权的用户信息。其中和权限有关的参数是Permission，您可以选择 FULL_CONTROL | READ | WRITE | READ_ACP | WRITE_ACP 来设定相应的权限。

返回结果

根据返回码判断是否操作成功。

获取桶访问权限

功能说明

您可以使用getBucketAcl接口获取桶的访问权限(ACL) ，以下代码展示如何获取桶的访问权限。

在调用 getBucketAcl 方法时，您需要传递的唯一参数是所选存储桶的名称。当前访问控制列表配置由在传递到回调函数的 data 参数中返回。

代码示例

var bucketParams = {
    Bucket: "<your-bucket-name>",
};
// call s3Client to retrieve policy for selected bucket
s3Client.getBucketAcl(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", data.Grants);
    }
});

请求参数

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

返回结果

参数	类型	说明
Grantee	Object	桶访问权限配置
Permission	String	桶访问权限

设置桶策略

功能说明

除了桶访问权限外，桶的拥有者还可以通过桶策略，提供对桶和桶内对象的集中访问控制。您可以在putBucketPolicy 接口中使用 JSON格式的文本字符串直接指定策略。

存储桶的策略主要包含以下元素：

参数	说明
Resource	可选关键字，指定statement起作用的一组资源，支持通配符“*”，表示所有资源
Action	可选关键字，指定本条statement作用的操作，Action字段为媒体存储支持的所有操作集合，以字符串形式表示，不区分大小写。支持通配符“*”，表示该资源能进行的所有操作
Effect	必选关键字，指定本条statement的权限是允许还是拒绝，Effect的值必须为Allow或者Deny
Principal	可选关键字，被授权人，指定本条statement权限针对的Domain以及User，支持通配符“”，表示所有用户（匿名用户）。当对Domain下所有用户授权时，Principal格式为arn:aws:iam:::user/。当对某个User进行授权时，Principal格式为arn:aws:iam:::user/<your-user-name>

代码示例

let policy = {
    Version: "2012-10-17",
    Statement: [{
        Sid: "AddPerm",
        Effect: "Allow",
        Principal: "*",
        Action: [
            "s3:GetObject"
        ],
        Resource: [
            "arn:aws:s3:::" + this.bucket + "/*"
        ]
    }]
};
let params = {
    Bucket: this.bucket,
    Policy: JSON.stringify(policy),
};
this.s3Client.putBucketPolicy(params, function(err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

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

返回结果

根据返回码判断是否操作成功。

获取桶策略

功能说明

在调用 getBucketPolicy 方法时，您需要传递的唯一参数是所选存储桶的名称。如果存储桶当前具有策略，该策略在由传递到回调函数的data参数中返回，如果所选存储桶没有策略，该信息将在error参数中返回给回调函数。

代码示例

var bucketParams = {
    Bucket: "<your-bucket-name>",
};
// call s3Client to retrieve policy for selected bucket
s3Client.getBucketPolicy(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", data.Policy);
    }
});

请求参数

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

返回结果

参数	类型	说明
Policy	Object	桶策略对象

关于Policy一些说明

参数	说明
Resource	指定statement起作用的一组资源，支持通配符“*”，表示所有资源
Action	指定本条statement作用的操作，Action字段为媒体存储支持的所有操作集合，以字符串形式表示，不区分大小写。支持通配符“*”，表示该资源能进行的所有操作
Effect	指定本条statement的权限是允许还是拒绝，Effect的值必须为Allow或者Deny
Principal	被授权人，指定本条statement权限针对的Domain以及User，支持通配符“”，表示所有用户（匿名用户）。当对Domain下所有用户授权时，Principal格式为arn:aws:iam:::user/。当对某个User进行授权时，Principal格式为arn:aws:iam:::user/<your-user-name>

删除桶策略

功能说明

您可以使用 deleteBucketPolicy接口刪除桶策略，以下代码展示如何刪除一个桶策略。

代码示例

var bucketParams = {
    Bucket: "<your-bucket-name>",
};
// call s3Client to delete policy for selected bucket
s3Client.deleteBucketPolicy(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", data);
    }
});

请求参数

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

返回结果

根据返回码判断是否操作成功。

设置桶生命周期配置

功能说明

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

代码示例

var params = {
    Bucket: "<your-bucket-name>",
    LifecycleConfiguration: {
        Rules: [
            {
                Expiration: {
                    Days: 3650,
                },
                Filter: {             //required
                    Prefix: '',
                },
                ID: 'TestOnly',
                Status: 'Enabled',    //required
                Transitions: [
                    {
                        Days: 365,
                        StorageClass: 'GLACIER',
                    },
                ],
                NoncurrentVersionExpiration: {
                    NoncurrentDays: 123,
                },
                AbortIncompleteMultipartUpload: {
                    DaysAfterInitiation: 123
                }
            },
        ],
    }
};

s3Client.putBucketLifecycleConfiguration(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

参数	类型	说明	是否必要
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接口获取桶的生命周期配置。

代码示例

var params = {
    Bucket: "<your-bucket-name>",
};

s3Client.getBucketLifecycleConfiguration(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", data);
    }
});

请求参数

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

返回结果

参数	类型	说明
Rules	Rule数组	一个描述生命周期管理的规则数组，一条规则包含了规则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接口删除桶的生命周期配置。

代码示例

// Set the parameters for s3Client.deleteBucketLifecycle
var bucketParams = {
    Bucket: "<your-bucket-name>",
};

s3Client.deleteBucketLifecycle(bucketParams, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else if (data) {
    console.log("Success", JSON.stringify(data.CORSRules));
  }
});

请求参数

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

返回结果

根据返回码判断是否操作成功。

设置桶跨域访问配置

功能说明

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

您可以通过 putBucketCors接口设置桶的跨域访问设置，以下为示例代码。

代码示例

var corsParams = {
    Bucket: "<your-bucket-name>",
    CORSConfiguration: {
        CORSRules: [{
            AllowedHeaders: ["*"],
            AllowedMethods: ["POST", "GET", "PUT", "DELETE", "HEAD"],
            AllowedOrigins: ["*"],
            ExposeHeaders: ["ETag"],
            MaxAgeSeconds: 3600,
        }],
    },
};
s3Client.putBucketCors(corsParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
CORSConfiguration	Object	CORS配置对象	是

返回结果

根据返回码判断是否操作成功。

获取桶跨域访问配置

功能说明

您可以使用getBucketCors接口获取桶的跨域访问配置，以下代码展示如何获取桶的跨域访问配置。

在调用 getBucketCors 方法时，您需要传递的唯一参数是所选存储桶的名称。如果存储桶当前具有 CORS 配置，该配置由传递到回调函数的 data 参数的 CORSRules 属性返回。如果所选存储桶没有 CORS 配置，该信息将在 error 参数中返回到回调函数。

代码示例

// Set the parameters for s3Client.getBucketCors
var bucketParams = {
    Bucket: "<your-bucket-name>",
};

// call s3Client to retrieve CORS configuration for selected bucket
s3Client.getBucketCors(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", JSON.stringify(data.CORSRules));
    }
});

请求参数

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

返回结果

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

关于CORSRules一些说明

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

删除桶跨域访问配置

功能说明

您可以通过 deleteBucketCors接口删除桶跨域访问设置，以下为示例代码。

在调用 deleteBucketCors 方法时，您需要传递的唯一参数是所选存储桶的名称。如果存储桶当前具有策略，该策略在由传递到回调函数的data参数中返回，如果所选存储桶没有跨域访问设置，该信息将在error参数中返回给回调函数。

代码示例

// Set the parameters for s3Client.deleteBucketCors
var bucketParams = {
    Bucket: "<your-bucket-name>",
};

// call s3Client to retrieve CORS configuration for selected bucket
s3Client.deleteBucketCors(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else if (data) {
        console.log("Success", JSON.stringify(data.CORSRules));
    }
});

请求参数

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

返回结果

根据返回码判断是否操作成功。

设置桶版本控制状态

功能说明

在开启版本控制功能后，上传同名对象将不再删除旧对象，而是添加一个新的对象。普通的删除操作也不会将对象彻底删除，而是添加一个 Delete Marker 作为标识。容器开启版本控制功能之后，无法再关闭该功能，只能暂停。桶的版本控制状态可以设置为以下的值：

Enabled：对bucket中的所有对象启用版本控制，之后每个添加到bucket中的对象都会被设置一个唯一的version id。
Suspended：关闭bucket的版本控制，之后每个添加到bucket中的对象的version ID会被设置为null。

代码示例

//开启版本控制
var params = {
    Bucket: "<your-bucket-name>",
    VersioningConfiguration: {
        Status: 'Enabled'
    },
};
s3Client.putBucketVersioning(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

//暂停版本控制
var params = {
    Bucket: "<your-bucket-name>",
    VersioningConfiguration: {
        Status: 'Suspended'
    },
};
s3Client.putBucketVersioning(params, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

参数	类型	说明	是否必要
Bucket	String	桶名称	是
VersioningConfiguration	Object	桶版本控制配置对象	是
Status	String	桶版本控制开关状态	是

返回结果

根据返回码判断是否操作成功。

获取桶版本控制状态

功能说明

媒体存储支持设置和存储一个对象的多个版本，使您更方便地检索和还原各个版本，以便可以快速恢复数据。您可以使用 getBucketVersioning接口获取版本控制状态，代码示例：

代码示例

// Create the parameters for calling getBucketVersioning
var bucketParams = {
    Bucket: "<your-bucket-name>",
};

// call S3 to getBucketVersioning
s3Client.getBucketVersioning(bucketParams, function (err, data) {
    if (err) {
        console.log("Error", err);
    } else {
        console.log("Success", data);
    }
});

请求参数

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

返回结果

参数	类型	说明
Status	String	桶版本控制状态

活动

智算服务

应用商城

定价

合作伙伴

开发者

支持与服务

了解天翼云

媒体存储

媒体存储

创建桶

功能说明

代码示例

请求参数

返回结果

获取桶列表

功能说明

代码示例

请求参数

返回结果

判断桶是否存在

功能说明

代码示例

请求参数

返回结果

删除桶

功能说明

代码示例

请求参数

返回结果

设置桶访问权限

功能说明

代码示例

请求参数

返回结果

获取桶访问权限

功能说明

代码示例

请求参数

返回结果

设置桶策略

功能说明

代码示例

请求参数

返回结果

获取桶策略

功能说明

代码示例

请求参数

返回结果

删除桶策略

功能说明

代码示例

请求参数

返回结果

设置桶生命周期配置

功能说明

代码示例

请求参数

返回结果

获取桶生命周期配置

功能说明

代码示例

请求参数

返回结果

删除桶生命周期配置

功能说明

代码示例

请求参数

返回结果

设置桶跨域访问配置

功能说明

代码示例

请求参数

返回结果

获取桶跨域访问配置

功能说明

代码示例

请求参数

返回结果