全部产品
Search
文档中心

对象存储 OSS:PutBucket

更新时间:Feb 19, 2024

调用PutBucket接口创建存储空间(Bucket)。

注意事项

  • 要创建存储空间,您必须有oss:PutBucket权限。具体操作,请参见为RAM用户授权自定义的权限策略

  • 同一阿里云账号在同一地域(Region)内最多支持创建100个存储空间。

  • 每个地域都有对应的访问域名(Endpoint)。关于地域与访问域名对应关系的更多信息,请参见访问域名和数据中心

  • 同账号同一个Bucket多次PutBucket请求,第一个请求是创建Bucket,后续请求是修改Bucket的元数据。多次PutBucket请求会有数据覆盖风险,请谨慎操作。

请求语法

PUT / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
x-oss-acl: Permission
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

请求头

名称

类型

是否必选

示例值

描述

x-oss-acl

字符串

private

指定存储空间的访问权限ACL。取值范围如下:

  • public-read-write:公共读写

  • public-read:公共读

  • private(默认):私有

关于存储空间访问权限ACL的更多信息,请参见设置存储空间访问权限ACL

x-oss-resource-group-id

字符串

rg-aek27tc****

指定资源组ID。

  • 如果在请求中携带该请求头并指定资源组ID,则创建的存储空间属于该资源组。

    当指定的资源组ID为rg-default-id时,创建的存储空间属于默认资源组。

  • 如果在请求中未携带该请求头,则创建的存储空间属于默认资源组。

您可以通过资源管理的控制台或ListResourceGroups接口获取资源组ID。具体操作,请分别参见查看资源组基本信息ListResourceGroups

x-oss-hns-status

字符串

disabled

指定存储空间是否开启分层命名空间。

只能在创建存储空间时设置是否开启分层命名空间。对于已存在的存储空间不能更改存储空间的分层命名空间状态。

  • enabled:开启

    存储空间开启分层命名空间后,您可以在存储空间中进行目录操作,例如创建目录、删除目录、重命名目录等。

  • disabled(默认):不开启

此接口还需要包含公共请求头。更多信息,请参见公共请求头(Common Request Headers)

请求元素

名称

类型

是否必选

示例值

描述

StorageClass

字符串

Standard

指定存储空间的存储类型。取值范围如下:

  • Standard(默认):标准存储

  • IA:低频访问

  • Archive:归档存储

  • ColdArchive:冷归档存储

  • DeepColdArchive:深度冷归档存储

父节点:CreateBucketConfiguration

子节点:无

DataRedundancyType

字符串

LRS

指定存储空间的数据容灾类型。取值范围如下:

  • LRS(默认)

    本地冗余LRS将您的数据冗余存储在同一个可用区的不同存储设备上,可支持两个存储设备并发损坏时,仍维持数据不丢失,可正常访问。

  • ZRS

    同城冗余ZRS采用多可用区(AZ)内的数据冗余存储机制,将用户的数据冗余存储在同一地域(Region)的多个可用区。当某个可用区不可用时,仍然能够保障数据的正常访问。

父节点:CreateBucketConfiguration

子节点:无

响应头

名称

类型

示例值

描述

Location

字符串

/oss-example

存储空间的地址。由/加上Bucket名称组成。

默认值:无

此接口还涉及其他公共响应头。更多信息,请参见公共响应头(Common Response Headers)

示例

  • 在默认资源组中创建存储空间

    PUT / HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2017 03:15:40 GMT
    x-oss-acl: private
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:77Dvh5wQgIjWjwO/KyRt8dOP****
    <?xml version="1.0" encoding="UTF-8"?>
    <CreateBucketConfiguration>
        <StorageClass>Standard</StorageClass>
        <DataRedundancyType>LRS</DataRedundancyType>    
    </CreateBucketConfiguration>
  • 返回示例

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2017 03:15:40 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
    Location: /oss-example
  • 在指定资源组中创建存储空间

    请求示例

    PUT / HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2017 03:15:40 GMT
    x-oss-acl: private
    x-oss-resource-group-id: rg-aek27tc********
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:77Dvh5wQgIjWjwO/KyRt8dOP****
    <?xml version="1.0" encoding="UTF-8"?>
    <CreateBucketConfiguration>
        <StorageClass>Standard</StorageClass>
    </CreateBucketConfiguration>

    返回示例

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2017 03:15:40 GMT
    Content-Length: 0
    Connection: keep-alive
    Server: AliyunOSS
    Location: /oss-example

SDK

此接口所对应的各语言SDK如下:

错误码

错误码

HTTP状态码

描述

InvalidBucketName

400

创建存储空间时,定义的存储空间名称不符合命名规范。

AccessDenied

403

返回该错误的可能原因如下:

  • 发起PutBucket请求时没有传入用户验证信息。

  • 没有操作权限。

TooManyBuckets

400

创建的存储空间数量超过上限。同一阿里云账号在同一地域(Region)内最多可创建100个存储空间。

BucketAlreadyExists

409

返回该错误的可能原因如下:

  • 该存储空间已存在或被其他用户占用。请尝试使用其他符合命名规范的存储空间名称新建存储空间。

  • 已存在的存储空间不能更改分层命名空间状态。只能在创建存储空间时设置是否开启分层命名空间。