All Products
Search

This Product

    Object Storage Service:PutBucket

    Document Center

    Object Storage Service:PutBucket

    Last Updated:May 22, 2023

    Creates a bucket.

    Usage notes

    • To create a bucket, you must have the oss:PutBucket permission. For more information, see Common examples of RAM policies.

    • You can create up to 100 buckets in the same region by using an Alibaba Cloud account.

    • Each region can be accessed by using the corresponding endpoints. For more information about regions and endpoints, see Regions and endpoints.

    Request syntax

    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>

    Request headers

    Header

    Type

    Required

    Example

    Description

    x-oss-acl

    String

    No

    private

    The access control list (ACL) of the bucket. Valid values:

    • public-read-write

    • public-read

    • private (default)

    For more information about the ACL of a bucket, see Bucket ACL.

    x-oss-resource-group-id

    String

    No

    rg-aek27tc****

    The ID of the resource group.

    • If you include the header in the request and specify the ID of the resource group, the bucket that you want to create belongs to the resource group.

      If the specified resource group ID is rg-default-id, the bucket that you want to create belongs to the default resource group.

    • If you do not include the header in the request, the bucket that you want to create belongs to the default resource group.

    You can obtain the ID of a resource group in the Resource Management console or by calling the ListResourceGroups operation. For more information, see View basic information of a resource group and ListResourceGroups.

    x-oss-hns-status

    String

    No

    disabled

    Specifies whether to enable the hierarchical namespace feature for the bucket.

    You can enable the hierarchical namespace feature only when you create a bucket. You cannot enable or disable the hierarchical namespace feature for existing buckets.

    • enabled

      After you enable the hierarchical namespace feature for a bucket, you can create, delete, and rename directories in the bucket.

    • disabled (default)

    The request headers involved in the PutBucket operation also contain common request headers. For more information about common request headers, see Common HTTP headers.

    Request elements

    Element

    Type

    Required

    Example

    Description

    StorageClass

    String

    No

    Standard

    The storage class of the bucket. Valid values:

    • Standard

    • IA

    • Archive

    • ColdArchive

    • DeepColdArchive

    Parent nodes: CreateBucketConfiguration

    Child nodes: none

    DataRedundancyType

    String

    No

    LRS

    The redundancy type of the bucket. Valid values:

    • LRS (default)

      Locally redundant storage (LRS) stores copies of each object across different devices in the same zone. This ensures data reliability and availability even if two storage devices are damaged at the same time.

    • ZRS

      Zone-redundant storage (ZRS) uses the multi-zone mechanism to distribute user data across multiple zones in the same region. If one zone becomes unavailable, you can continue to access the data that is stored in other zones.

    Parent nodes: CreateBucketConfiguration

    Child nodes: none

    Response headers

    The response to a PutBucket request contains only common response headers. For more information about common response headers, see Common HTTP headers.

    Examples

    • Create a bucket in the default resource group

      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>

    • Sample success responses

      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

    • Create a bucket in a specific resource group

      Sample requests

      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>

      Sample success responses

      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

    SDK

    You can use Object Storage Service (OSS) SDKs for the following programming languages to call the PutBucket operation:

    Error codes

    Error code

    HTTP status code

    Description

    InvalidBucketName

    400

    The bucket name does not comply with the naming conventions.

    AccessDenied

    403

    Possible causes:

    • The information for user authentication is not imported when you initiate the PutBucket request.

    • You do not have the permissions to perform the PutBucket operation.

    TooManyBuckets

    400

    The number of buckets created exceeds the upper limit. You can create up to 100 buckets in the same region by using an Alibaba Cloud account.

    BucketAlreadyExists

    409

    Possible causes:

    • This bucket already exists or is occupied by another user. Use a new bucket name that complies with the naming conventions.

    • You cannot enable or disable the hierarchical namespace feature for existing buckets. You can enable the hierarchical namespace feature only when you create a bucket.