PUT Bucket

You can send the PUT Bucket request to create a bucket with the specified name.

Note

  • You can create a maximum of 100 buckets.

  • You can enable WORM when you create a bucket, but you cannot enable WORM for an existing bucket. In a bucket with WORM enabled, you can further configure retention policies for objects you upload to this bucket. For more information, see Configuring a Default WORM Policy for a Bucket. Once enabled, WORM cannot be disabled for a bucket. When you create a bucket with WORM enabled, OBS automatically enables versioning for the bucket and the versioning cannot be suspended for that bucket. When you create a parallel file system, you cannot enable WORM for it.

The name of a bucket must be unique in OBS. If a user repeatedly creates namesake buckets in the same region, status code 200 is returned. If namesake buckets are repeatedly created in other cases, status code 409 is returned. You can set the ACL of a bucket by adding optional header x-amz-acl to a request.

Note

In multiple regions scenarios, if user A creates a bucket, deletes the bucket later, and immediately creates a bucket with the same name in different regions, the system will respond 409. If user A creates a bucket with the same name in different regions 30 minutes later, the system will respond 200.

If a 5xx error is returned from the server or the request times out during bucket creation, the system takes about 10 minutes to make bucket information consistent. During the process, bucket information is inaccurate.

Request Syntax

PUT / HTTP/1.1
 User-Agent: agent
 Host: Host Server
 Accept: */*
 Date: date
 Authorization: authorization
 Content-Length: 0
 <Optional Additional Header>

 <CreateBucketConfiguration xmlns="http://obs.example.com/doc/2015-06-30/">
 <LocationConstraint>location</LocationConstraint>
 </CreateBucketConfiguration>

Request Parameters

This request involves no parameters.

Request Headers

This request uses common headers. For details about common request headers, see section Common Request Headers.

You can add optional headers to this request. Table 1 describes the optional headers.

Table 1 Optional request headers

Header

Description

Remarks

x-amz-acl

Indicates the ACL of a bucket. Possible values are private, public-read, public-read-write, authenticated-read, bucket-owner-read, and bucket-owner-full-control. For details, see Table 4.

Type: String

Optional

x-amz-security-token

Header field used to identify the request of a federated user. When the federal authentication function is enabled, users sending such requests are identified as federated users.

Type: string

Optional. This parameter must be carried in the request sent by federated users.

x-amz-bucket-object-lock-enabled

When creating a bucket, you can use this header to enable WORM for the bucket.

Type: string

Example: x-amz-bucket-object-lock-enabled:true

No

Request Elements

This request contains one element, as described in Table 2

Table 2 Request element

Element

Description

Remarks

LocationConstraint

Indicates the Region where a bucket will be created. This element is contained in CreateBucketConfiguration.

Type: String

Optional

Response Syntax

HTTP/1.1 status_code
 x-amz-request-id: request id
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 Location: location
 x-amz-id-2: id
 Date: date
 Content-Length: 0

Response Headers

This response uses common headers. For details about common response headers, see section Common Response Headers.

Response Elements

This response involves no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 1.

Sample Request

PUT / HTTP/1.1
 User-Agent: Jakarta Commons-HttpClient/3.1
 Host: bucketname.obs.example.com
 Accept: */*
 Date: Sat, 03 Dec 2011 06:31:58 +0000
 Authorization: AWS BF6C09F302931425E9A7:QBaO+tS/76QYHVnUoxvf9EPH/3o=
 Content-Length: 0

Sample Response

HTTP/1.1 200 OK
 Server: OBS
 x-amz-request-id: 001B21A61C6C00000134029F41D1527F
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 Location: /bucketname
 x-amz-id-2: MDAxQjIxQTYxQzZDMDAwMDAxMzQwMjlGNDFEMTUyN0ZBQUFBQUFBQWJiYmJiYmJi
 Date: Sat, 03 Dec 2011 06:31:58 GMT
 Content-Length: 0

Sample Request (Example of Setting the Region of a Bucket)

PUT / HTTP/1.1
 User-Agent: Jakarta Commons-HttpClient/3.1
 Host: bucketname.obs.example.com
 Accept: */*
 Date: Sat, 03 Dec 2011 06:31:58 +0000
 Authorization: AWS BF6C09F302931425E9A7:QBaO+tS/76QYHVnUoxvf9EPH/3o=
 Content-Length: 149

<CreateBucketConfiguration xmlns="http://obs.example.com/doc/2015-06-30/">
<LocationConstraint>EU</LocationConstraint>
</CreateBucketConfiguration>

Sample Response (Example of Setting the Region of a Bucket)

HTTP/1.1 200 OK
 Server: OBS
 x-amz-request-id: 001B21A61C6C00000134029F41D1527F
 x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
 Location: /bucketname
 x-amz-id-2: MDAxQjIxQTYxQzZDMDAwMDAxMzQwMjlGNDFEMTUyN0ZBQUFBQUFBQWJiYmJiYmJi
 Date: Sat, 03 Dec 2011 06:31:58 GMT
 Content-Length: 0

Sample Request for Creating a Bucket with WORM Enabled

PUT / HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 02:25:05 GMT
Authorization: authorization
x-amz-bucket-object-lock-enabled:true
Content-Length: 0

Sample Response for Creating a Bucket with WORM Enabled

HTTP/1.1 200 OK
Server: OBS
x-amz-request-id: 00000184C11AC7A6809F881341842C02
x-reserved-indicator: Unauthorized
Location: /examplebucket
x-amz-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT9W2tcvLmMJ+plfdopaD62S0npbaRUz
Date: WED, 01 Jul 2015 02:25:06 GMT
Content-Length: 0