All Products
Search
Document Center

Object Storage Service:PutBucket

Last Updated:Mar 08, 2024

Creates a bucket.

Usage notes

  • To create a bucket, you must have the oss:PutBucket permission. For more information, see Attach a custom policy to a RAM user.

  • 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, see Regions and endpoints.

  • If multiple PutBucket operations are called from the same Alibaba Cloud account to create the same bucket, the first operation creates the bucket and subsequent operations modify the metadata of the bucket. Exercise caution when you call multiple PutBucket operations on the same bucket, because doing so can cause accidental data overwriting.

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 ACLs.

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.

To obtain the ID of a resource group, you can use the Resource Management console or call 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 in a PutBucket request 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 (default)

  • 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) stores data across multiple zones in the same region. Your data is still accessible even if a zone becomes unavailable.

Parent nodes: CreateBucketConfiguration

Child nodes: none

Response headers

Header

Type

Example

Description

Location

String

/oss-example

The URL of the bucket. The header consists of a forward slash (/) and the name of the bucket.

This header is empty by default.

The response to a PutBucket request contains common response headers. For more information, see Common response 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 response

    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
  • Create a bucket in a specific resource group

    Sample request

    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 response

    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

You can use OSS SDKs for the following programming languages to call PutBucket:

Error codes

Error code

HTTP status code

Description

InvalidBucketName

400

The bucket name does not meet the naming requirements.

AccessDenied

403

Possible causes:

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

  • You do not have the permissions to call 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 meets the naming requirements.

  • 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.