PUT Bucket

描述

此 PUT 操作将为用户创建一个新的空间。

注意事项

• 用户需要是已注册用户，并且使用有效的 Access Key ID 验证来发送请求。任何匿名请求都不会被允许创建用户空间。
• 用户将成为其创建空间的拥有者，拥有者有头等权限。
• 同一用户创建的Bucket总数不能超过100个。

存储空间命名规则

如果您使用 KS3 管理控制台，则在所有区域中，存储空间名称都必须符合 DNS 标准。符合 DNS 标准的存储空间名称使客户能够受益于新功能和操作改进，并支持对存储空间进行虚拟托管类型访问。符合 DNS 标准的存储空间名称规则如下：

• 存储空间名称的长度必须为至少 3 个字符，且不能超过 63 个字符。

• 存储空间名称必须是一系列的一个或多个标签，标签间可以用连字符（-）连接。存储空间名称只能包含小写字母、数字和连字符（-），且不能以连字符（-）开头或结尾。

以下示例是有效存储空间名称：

• my-ksbucket
• myksbucket123
• 123myksbucket

以下示例是无效存储空间名称：

• -myksbucket 存储段名称不能以连字符 (-) 开始。
• myksbucket- 存储段名称不能以连字符 (-) 结束。
• my.ksbucket 存储段名称不能包含句点(.)。

设置存储空间所属项目组

用户可以使用参数projectId将存储空间（Bucket）分配到不同的项目组中，未指派项目信息的存储空间(Bucket)将默认分配到默认项目组中，默认项目组为0。

设置存储空间访问权限

当用户使用此接口创建空间时，用户可以授予其他用户或者群组关于此空间的操作权限。以下列出了通过请求头部实现的两种授权方式。

• 使用 x-kss-acl 请求头部，指定一个预定义的 ACL。该请求头部可为所有用户设置访问权限，一般需要设置为私有类型。
• 使用 x-kss-grant-read,x-kss-grant-write,x-kss-grant-full-control 请求头部，可为指定用户设置访问权限。

设置存储空间存储类型

用户可以通过x-kss-bucket-type请求头指定Bucket类型。

• NORMAL表示非归档存储Bucket，若上传时，不指定Object存储类型则默认为标准存储类型
• ARCHIVE表示归档存储Bucket，若上传时，不指定Object存储类型则默认为归档存储类型

请求

简单请求语法

PUT / HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LocationConstraint>{BucketRegion}</LocationConstraint>
</CreateBucketConfiguration>

指定项目组时请求语法

PUT /?projectId={projectId} HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LocationConstraint>{BucketRegion}</LocationConstraint>
</CreateBucketConfiguration>

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

该接口不使用请求参数。

请求头部

该接口可以使用常用请求头部。获取更多信息，请点击常用请求头部

用户可以通过x-kss-bucket-type请求头指定Bucket类型，NORMAL表示非归档存储Bucket，ARCHIVE表示归档存储Bucket

名称	描述	是否必选
x-kss-bucket-type	用于指定Bucket类型。 类型：String 默认值：NORMAL 有效值：NORMAL ARCHIVE 约束条件：无	否

用户可以使用以下header为Bucket设置一个预设的ACL

名称	描述	是否必选
x-kss-acl	用于存储空间的预定义权限。 类型：String 默认值：private 有效值：private public-read public-read-write 约束条件：无	否

用户可以使用以下header为Bucket设置详细的ACL

名称	描述	是否必选
x-kss-grant-read	为若干用户授予READ权限。 类型：String 默认值：无 约束条件：无	否
x-kss-grant-write	为若干用户授予WRITE权限。 类型：String 默认值：无 约束条件：无	否
x-kss-grant-full-control	为若干用户授予FULL_CONTROL权限。 类型：String 默认值：无 约束条件：无	否

以上header值的值为以一个逗号","分割的授权列表。每个授权信息的格式为type=value，当前type支持被授权者的用户id。

• 例如，要给id为1234578和3344211的两个用户授予WRITE权限:
  x-kss-grant-write:id=“1234578”,id=“3344211”

请求内容

名称	描述	是否必选
CreateBucketConfiguration	用户空间配置信息的容器。 类型: Container 父节点: None	否
LocationConstraint	指定用户空间将要被创建的区域。 类型: String 有效值: BEIJING SHANGHAI HONGKONG GUANGZHOU RUSSIA SINGAPORE Default: BEIJING 父节点: CreateBucketConfiguration	否

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。

响应内容

该接口不返回响应内容。

示例

简单请求示例

PUT / HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Content-Length: 0
Date: Fri, 26 Dec 2014 06:30:04 GMT
Authorization: authorization string

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <LocationConstraint>BEIJING</LocationConstraint>
</CreateBucketConfiguration>

响应示例

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:30:04 GMT
Content-Length: 0
Connection: keep-alive
x-kss-request-id: f86r2t80lgj8bs6ksd8qrnorlkf4kmib
Server: KS3

指定项目组时请求示例

PUT /?projectId=111 HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Content-Length: 0
Date: Fri, 26 Dec 2014 06:30:04 GMT
Authorization: authorization string

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <LocationConstraint>BEIJING</LocationConstraint>
</CreateBucketConfiguration>

响应示例

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:30:04 GMT
Content-Length: 0
Connection: keep-alive
x-kss-request-id: fkm46t80hek8bs6kvh8qvno5lne4oqv2
Server: KS3

错误码

错误码	HTTP状态码	描述
InvalidBucketName	400	定义的Bucket名称不符合命名规范。
TooManyBuckets	400	创建的Bucket数量超过上限。同一用户创建的Bucket总数不能超过100个。
BucketAlreadyExists	409	该Bucket已经存在。