On this page

Functions
Storage Class
Request Syntax
Request Parameters
Request Headers
Request Elements
Response Syntax
Response Headers
Response Elements
Error Responses
Sample Request: Creating a Bucket
Sample Response: Creating a Bucket
Sample Request: Creating a Bucket (with the ACL and Storage Class Specified)
Sample Response: Creating a Bucket (with the ACL and Storage Class Specified)
Sample Request: Creating a Parallel File System
Sample Response: Creating a Parallel File System

Show all

Help Center/ Object Storage Service/ API Reference (Kuala Lumpur Region)/ APIs/ Operations on Buckets/ Creating a Bucket

Creating a Bucket

Updated on 2024-03-05 GMT+08:00

View PDF

Functions

This operation is used to create a bucket with a specified name.

NOTE:

By default, a user can have a maximum of 100 buckets.
The name of a deleted bucket can be reused for a bucket or a parallel file system at least 30 minutes after the deletion.

A bucket name must be unique in OBS. If a user creates a bucket with the same name as that of an existing bucket under the same account and in the same region, a 200 code (indicating success) is returned. In scenarios other than the preceding one, the request for creating a bucket with the same name as that of an existing one will receive the 409 code (indicating that a namesake bucket already exists). To set an access control policy for the bucket to be created, you can add the x-obs-acl parameter to request headers.

Storage Class

You can create buckets with different storage classes. The x-obs-storage-class header in a bucket creation request specifies the bucket's storage class. If you do not specify a storage class when you upload an object to the bucket, the object inherits the storage class of the bucket. The storage class options are as follows: STANDARD (Standard), WARM (Warm), COLD (Cold). If the x-obs-storage-class header is not in the request, a Standard bucket will be created.

If the storage class of an object is not specified when it is uploaded to a bucket (see Uploading an Object - PUT), the object will be stored in the default storage class of the bucket.

OBS Standard features low access latency and high throughput. It is most suitable for storing frequently accessed (multiple times per month) hot files. Potential application scenarios include big data, mobile applications, trending videos, and social media images.
OBS Warm storage class is suitable for storing data that is infrequently accessed (less than 12 times a year) yet has quick response requirements. Potential application scenarios include file synchronization or sharing and enterprise backup. It provides the same durability, access latency, and throughput as the Standard storage class but at a lower price. However, the Warm storage class has lower availability than the Standard one.
OBS Cold storage class is applicable to archiving rarely-accessed (averagely once a year) data. The application scenarios include data archiving and long-term data retention for backup. The Cold storage class is secure, durable, and inexpensive, which can replace tape libraries. To keep cost low, it may take hours to restore data from the Cold storage class.

Request Syntax

    
       PUT / HTTP/1.1 
Host: bucketname.obs.region.example.com
Content-Length: length
Date: date
Authorization: authorization
 
<CreateBucketConfiguration xmlns="http://obs.region.example.com/doc/2015-06-30/">
    <Location>location</Location> 
</CreateBucketConfiguration>

Request Parameters

This request contains no parameters.

Request Headers

The operation message header is the same as that of a common request. For details, see Table 3. However, this request can contain additional headers. The following table describes the additional headers for this request.

**Table 1** Additional request headers
Header	Description	Mandatory
x-obs-acl	When creating a bucket, you can add this header to set the permission control policy for the bucket. The predefined common policies are as follows: private, public-read, public-read-write, public-read-delivered, and public-read-write-delivered. Type: string	No
x-obs-storage-class	When creating a bucket, you can add this header to specify the default storage class for the bucket. The storage class options are as follows: STANDARD (Standard), WARM (Warm), and COLD (Cold). If this header is not in the request, a Standard bucket will be created. Type: string	No
x-obs-grant-read	This header grants the read permission to all users under an account. It allows you to list objects in a bucket, list multipart tasks in a bucket, list multi-version objects in a bucket, and obtain bucket metadata. Type: string Example: x-obs-grant-read:id=Tenant ID	No
x-obs-grant-write	This header grants the write permission to all users under an account. Therefore, the users can create, delete, and overwrite all objects in a bucket, and can initialize parts, upload parts, copy parts, merge parts, and cancel multipart upload tasks. Type: string Example: x-obs-grant-write:id=Tenant ID	No
x-obs-grant-read-acp	This header grants the ACL read permission to all users under an account. Therefore, the users can read the bucket ACL information. Type: string Example: x-obs-grant-read-acp:id=Account ID	No
x-obs-grant-write-acp	This header grants the ACL write permission to all users under an account. Therefore, the users can modify the ACL of the bucket. Type: string Example: x-obs-grant-write-acp:id=Account ID	No
x-obs-grant-full-control	This header grants the full control permission to all users under an account. Type: string Example: x-obs-grant-full-control:id=Account ID	No
x-obs-grant-read-delivered	This header grants the read permission to all users under an account. By default, the read permission is applied to all objects in the bucket. Type: string Example: x-obs-grant-read-delivered:id=Account ID	No
x-obs-grant-full-control-delivered	This header grants the full control permission to all users under an account. By default, the FULL_CONTROL permission is applied to all objects in the bucket. Type: string Example: x-obs-grant-full-control-delivered:id=Account ID	No
x-obs-fs-file-interface	This header can be carried when you create a bucket as a parallel file system. Type: string Example: x-obs-fs-file-interface:Enabled	No
x-obs-epid	Enterprise project ID, which can be obtained from the enterprise project service. The value is a universally unique identifier (UUID). The value of a default enterprise project is 0 or does not contain this header. Users who have not enabled the enterprise project service do not need to carry this header either. Type: string Example: x-obs-epid:9892d768-2d13-450f-aac7-ed0e44c2585f	No

Request Elements

This request can use additional elements. For details about additional elements, see Table 2.

**Table 2** Additional request elements
Element	Description	Mandatory
Location	Specifies the region where a bucket will be created. When creating a bucket using the endpoint of the default region, note the following: If Location is not specified, the bucket is created in the default region. If Location is specified to other region, the bucket is created in the specified region. When creating a bucket using the endpoint of a non-default region, Location must be specified to the region corresponding to the endpoint. For details about OBS regions and endpoints, see Endpoints. Type: string	No

Response Syntax

    
       HTTP/1.1 status_code
Location: location
Date: date
Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

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

Sample Request: Creating a Bucket

    
       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: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Length: 157

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

Sample Response: Creating a Bucket

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

Sample Request: Creating a Bucket (with the ACL and Storage Class Specified)

    
       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
x-obs-acl:public-read
x-obs-storage-class:STANDARD
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Length: 157

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

Sample Response: Creating a Bucket (with the ACL and Storage Class Specified)

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

Sample Request: Creating a Parallel File System

    
       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: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Length: 157
x-obs-fs-file-interface: Enabled

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

Sample Response: Creating a Parallel File System

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

Parent topic: Operations on Buckets

Previous topic: Listing Buckets

Next topic: Listing Objects in a Bucket

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot