Help Center/ Object Storage Service/ API Reference (Ally Region)/ APIs/ Operations on Buckets/ Creating a Bucket
Updated on 2026-01-16 GMT+08:00
View PDF
Share

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.
  • OBS buckets are global resources, so each bucket name must be unique across all users, including your own. To reuse the name of a deleted bucket for another bucket, you must wait until the bucket name is released. Deleting a bucket via API takes about 30 minutes. However, the process may take longer if the bucket is not empty, or if the account is in arrears or has been deregistered. OBS cannot guarantee immediate deletion. Therefore, if you attempt to create a new bucket using a name that has not been released, the creation will fail. Similarly, if the name is released but claimed by another user before you reuse it, the creation will also fail.

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 with 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. However, the low cost comes at the cost of minutes to hours needed to restore data from the Cold storage class.

Request Syntax

1
2
3
4
5
6
7
8
9
 
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. Note that the bucket name is specified in the Host field of Table 3.

Table 1 Additional request headers

Header

Type

Mandatory (Yes/No)

Description

x-obs-acl

String

No

Definition:

When creating a bucket, you can use this parameter to set a pre-defined ACL.

Range:

  • private: A bucket or an object can be accessed only by its owner.
  • public-read: If this permission is granted on a bucket, anyone can read the object list, multipart uploads, and bucket metadata.
  • public-read-write: If this permission is granted on a bucket, anyone can obtain the object list, multipart tasks, and metadata, and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and cancel multipart upload tasks.
  • public-read-delivered: If this permission is set for a bucket, everyone can obtain the object list, multipart uploads, and bucket metadata in the bucket, and obtain the content and metadata of the objects in the bucket.
  • public-read-write-delivered: If this permission is set for a bucket, everyone can obtain the object list in the bucket, multipart uploads in the bucket, and metadata of the bucket; upload and delete objects; initiate multipart uploads; upload, assemble, and copy parts; cancel multipart uploads; and obtain content and metadata of objects in the bucket.
  • bucket-owner-full-control: If this permission is granted on an object, only the bucket and object owners have the full control over the object.

    By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this policy to the bucket owner, the bucket owner can have full control over your object.

    For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets the bucket-owner-full-control policy for object x, user B then has the control over object x.

Default value:

private

x-obs-storage-class

String

No

Definition:

When creating a bucket, you can add this header to set the default storage class for the bucket.

Range:

  • STANDARD (Standard storage)
  • WARM (Warm storage)
  • COLD (Cold storage)

Default value:

STANDARD

x-obs-grant-read

String

No

Definition:

Grants the read permission to all users in a specified domain. 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.

Example: x-obs-grant-read:id=tenant-ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-write

String

No

Definition:

Grants the WRITE permission to all users in a specified domain to create, delete, and overwrite all objects in a bucket; and initiate multipart uploads, upload parts, copy parts, assemble parts, and cancel multipart uploads.

Example: x-obs-grant-write:id=tenant-ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-read-acp

String

No

Definition:

Grant the READ_ACP permission to all users in a specified domain to allow them to read the bucket ACL.

Example: x-obs-grant-read-acp:id=Account ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-write-acp

String

No

Definition:

Grants the WRITE_ACP permission to all users in a specified domain to allow them to modify the bucket ACL.

Example: x-obs-grant-write-acp:id=Account ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-full-control

String

No

Definition:

Grants the FULL_CONTROL permission to all users in a specified domain.

Example: x-obs-grant-full-control:id=tenant-ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-read-delivered

String

No

Definition:

Grants the READ permission to all users in a specified domain. By default, the read permission is granted on all objects in the bucket.

Example: x-obs-grant-read-delivered:id=tenant-ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-grant-full-control-delivered

String

No

Definition:

Grants the FULL_CONTROL permission to all users in a specified domain. By default, the FULL_CONTROL permission is granted on all objects in the bucket.

Example: x-obs-grant-full-control-delivered:id=tenant-ID

Constraints:

None

Range:

id=tenant-ID. For details, see Obtaining a Domain ID and a User ID.

Default value:

None

x-obs-fs-file-interface

String

No

Definition:

This header can be carried when you want to create a parallel file system.

Example: x-obs-fs-file-interface:Enabled

Range:

Enabled

Default value:

If the header is specified, the value must be Enabled. There is no default value.

x-obs-epid

String

No

Definition:

Enterprise project ID. Users who have enabled the enterprise project function can obtain this ID in UUID format from the enterprise project service. The default project ID is 0. This header can be not included. This header is not required for users who have not enabled the enterprise project function.

Example: x-obs-epid:9892d768-2d13-450f-aac7-ed0e44c2585f

Constraints:

None

Range:

The value can be 0 or your actual enterprise project ID.

Default value:

0

Request Elements

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

Table 2 Additional request elements

Element

Type

Mandatory (Yes/No)

Description

Location

String

No

Definition:

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

Range:

For details about OBS regions and endpoints, see Endpoints.

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 contains no elements.

Error Responses

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

Sample Request: Creating 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.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

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: Creating a Bucket (with the ACL and Storage Class Specified)

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

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: Creating 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.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

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