Help Center> Object Storage Service> API Reference> APIs> Operations on Buckets> Creating a Bucket
View PDF

Creating a Bucket

Functions

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

  • 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.
  • When creating a bucket in OBS, you can enable the multi-AZ mode for the bucket or disable it. When the multi-AZ mode is disabled, data in the bucket is stored in a single AZ by default. When the multi-AZ mode is enabled, data in the bucket is duplicated and stored in multiple AZs. However, buckets created before are still in the single AZ mode.

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 default storage class for a bucket. The storage class of the objects in a bucket is the same as that of the bucket. OBS provides three storage classes: Standard (STANDARD), Infrequent Access (WARM), and Archive (COLD). If this header is not in the request, the storage class of the created bucket is Standard.

If the storage class of an object is not specified when it is uploaded to a bucket (see Uploading Objects - 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 Infrequent Access is most suitable for storing semi-frequently accessed (less than 12 times a year) data requiring quick response. Potential application scenarios include file synchronization or sharing and enterprise-level backup. It provides the same durability, access latency, and throughput as the Standard but at a lower price. The main drawback, however, is that it has lower availability than the Standard.
  • OBS Archive is most suitable for archiving rarely-accessed (averagely once a year) data. Potential application scenarios include data archiving and long-term data retention for backup. It provides secure, durable, and inexpensive storage, which can replace tape libraries. However, it may take hours to retrieve data from the Archive storage class.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
PUT / HTTP/1.1 
Host: bucketname.obs.cn-north-4.myhuaweicloud.com 
Content-Length: length
Date: date
Authorization: authorization
x-obs-az-redundancy: 3az

<CreateBucketConfiguration xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> 
    <Location>location</Location> 
</CreateBucketConfiguration>

Request Parameters

This request contains no parameter.

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, public-read-write-delivered, and bucket-owner-full-control. For details about the policies, see the ACL configuration using header fields in ACL.

Type: string

No

x-obs-storage-class

When creating a bucket, you can add this header to specify the default storage class of the bucket. OBS provides three storage classes by default: OBS provides three storage classes: Standard (STANDARD), Infrequent Access (WARM), and Archive (COLD). If this header is not in the request, the storage class of the bucket created is Standard.

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-az-redundancy

This header is carried in the request when creating a bucket to enable the multi-AZ mode for the bucket. If this header is not carried, the bucket is in the single AZ mode by default. This header is carried to specify that a newly created bucket uses multi-AZ storage. If the region where the bucket resides does not support multi-AZ storage, the bucket still uses the single-AZ storage.

Type: string

Example: x-obs-az-redundancy:3az

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 using the endpoint of CN North-Beijing1 to create a bucket, note the following:
    • If Location is not specified, the bucket is created in CN North-Beijing1 (cn-north-1) by default.
    • If Location is specified, for example, CN North-Beijing4 (cn-north-4), the bucket is created in the specified region.
  • When creating a bucket using the endpoint of a region other than CN North-Beijing1, Location must be specified to the region corresponding to the endpoint.

    For example, when creating a bucket using the obs.cn-north-4.myhuaweicloud.com endpoint, set Location to cn-north-4.

Type: string

No

Response Syntax

1
2
3
4
 
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 involves no elements.

Error Responses

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

Sample Request 1

Create a bucket.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT / HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 02:25:05 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Length: 157

<CreateBucketConfiguration xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> 
    <Location>cn-north-4</Location>
</CreateBucketConfiguration>

Sample Response 1

1
2
3
4
5
6
7
 
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 2

Create a bucket with a specified ACL and storage class.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 
PUT / HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.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.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> 
    <Location>cn-north-4</Location> 
</CreateBucketConfiguration>

Sample Response 2

1
2
3
4
5
6
7
 
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 3

Select multi-AZ when creating a bucket.

1
2
3
4
5
6
7
8
9
 
PUT / HTTP/1.1 
Host: examplebucket.obs.cn-north-4.myhuaweicloud.com
Content-Length: length 
Date: date 
Authorization: authorization 
x-obs-az-redundancy:3az 
<CreateBucketConfiguration xmlns="http://obs.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> 
 <Location>cn-north-4</Location> 
</CreateBucketConfiguration>

Sample Response 3

1
2
3
4
5
6
7
8
 
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 
x-obs-az-redundancy:3az
Content-Length: 0

Sample Request 4

Create a parallel file system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
 
PUT / HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.cn-north-4.myhuaweicloud.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.cn-north-4.myhuaweicloud.com/doc/2015-06-30/"> 
<Location>cn-north-4</Location> 
</CreateBucketConfiguration>

Sample Response 4

1
2
3
4
5
6
7
 
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