PUT Bucket

Description

This PUT operation will create a new bucket for the user. The user needs to be a registered user and use valid Access Key ID authentication to send the request. No anonymous request will be allowed to create a user bucket. Users will be the owners of their creation bucket, with the highest permissions.

Naming rules for bucket

We recommend that all storage space names follow DNS naming conventions.

Note: If you use the KS3 management console, the storage name must be DNS compliant in all regions.

DNS compliant storage space names enable customers to benefit from new features and operational improvements, and support virtual managed type access to storage space. There is only one unified naming method for storage space. DNS compliant storage name rules are as follows:

• The storage space name must be at least 3 characters long and cannot exceed 63 characters.

• The storage space name must be a series of one or more labels, which can be connected with hyphens (-). Storage space names can contain lowercase letters, numbers, hyphens (-), and cannot contain periods (.). The storage space name must start and end with a lowercase letter or number.

• The name of the storage space must not be in IP address format (for example, 192.168.5.4).

The following example is a valid storage space name:

• my-ksbucket
• myksbucket123
• 123myksbucket

The following example is an invalid storage name:

• -myksbucket The bucket name cannot start with a hyphen (-).
• myksbucket- The bucket name cannot end with a hyphen (-).
• my.ksbucket The bucket name cannot contain a period (.).

When users use this interface to create a space, they can grant other users or groups permission to operate on the space. The following lists two authorization methods implemented by request headers.

• Use the x-kss-acl request header to specify a predefined 'ACL'.
• Use x-kss-grant-read,x-kss-grant-write and x-kss-grant-full-control request headers to specify specific access rights.

Request

Grammar

PUT / HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LocationConstraint>{BucketRegion}</LocationConstraint>
</CreateBucketConfiguration>

Note:

• Corresponding relationship between Endpoint and Region
• SignatureValue signature algorithm

Request parameters

The interface does not use request parameters.

Request header

This interface can use common request headers. For more information, please click Public request headers.

Users can specify the bucket type through the x-kss-bucket-type request header, NORMAL for non archive storage Bucket, ARCHIVE for archive storage Bucket.

The user can use the following header to set a preset ACL for the bucket

Users can use the following headers to set detailed ACL for buckets

The value of the above header value is a comma separated authorization list. The format of each authorization information is type = value. The current type supports ID:

• ID: user ID of the authorized person

For example, to grant WRITE permission to two users with ID 1234578 and 3344211: x-kss-grant-write:id="1234578",id="3344211"

Request content

Response

Response header

This interface can use all common response headers. For more information, please click Public response headers.

Response content

The interface does not return the corresponding content.

Special errors

The interface does not return any special errors.

Example

Request example

PUT / HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Content-Length: 0
Date: Fri, 26 Dec 2014 06:30:04 GMT
Authorization: authorization string

Response example

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:30:04 GMT
Content-Length: 0
Connection: close
Server: Tengine

Interface details

• The bucket name is globally unique. If the name of new bucket already exists, KS3 will return 409.
• For most users, setting ACL with x-kss-acl is enough. For bucket, it is usually set to private.