Description
This API is used to create a bucket under a specified account. A signature needs to be carried in Authorization and anonymous calls are not supported. By default, the bucket creator is the bucket owner.
Notes
If no access permission is specified for a bucket when it is created, private (private read/write) will be used by default.
Request
Syntax example:
PUT / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (See Request Signature for details.)
Request Line
PUT / HTTP/1.1
This API accepts PUT requests.
Request Header
Common headers:
This request is implemented by using common request headers. For details on common request headers, see the Common Request Headers section.
Non-common headers:
This request is implemented by using the x-cos-acl header in PUT requests to set the bucket access permissions. Currently, bucket access permissions are divided into three types: public-read-write, public-read, and private. If the permission is not set, private is configured by default. The read, write, or read-write permissions can also be granted individually to users. Details are as follows:
For more information about ACL requests, see Put Bucket ACL.
| Name | Description | Type | Required |
|---|---|---|---|
| x-cos-acl | Defines the acl attribute of an object. Valid values are private, public-read, and public-read-write, and the default value is private. | String | No |
| x-cos-grant-read | Grants read access to the grantee. Format: x-cos-grant-read: id=" ",id=" "; Grants access permissions to root account only, id="qcs::cam::uin/ :uin/" |
String | No |
| x-cos-grant-write | Grants write permission to the grantee. Format: x-cos-grant-write: id=" ",id=" "; Grants access permissions to root account only, id="qcs::cam::uin/ :uin/" |
String | No |
| x-cos-grant-full-control | Grants read/write permission to the grantee. Format: x-cos-grant-full-control: id=" ",id=" "; Grants access permissions to root account only, id="qcs::cam::uin/ :uin/" |
String | No |
Request Body
The request body of this request is empty.
Response
Response Headers
Common Response Headers
This response uses common response headers. For details, see Public Response Header.
Special Response Headers
There are no special response headers for this response operation.
Response Body
The response body is empty.
Error Analysis
The following describes some special but common errors that may occur with this request:
| Error Code | HTTP Status Code | Description |
|---|---|---|
| BucketAlreadyExists | 409 Conflict | The specified bucket already exists and is owned by the current account. |
| InvalidBucketName | 400 Bad Request | The bucket name is invalid. For more information, see message description. |
| InvalidRequest | 400 Bad Request | The bucket name is invalid. For more information, see message description. |
If the ACL set for the bucket is incorrect, bucket creation will fail and the error message Failed to set access control authority for the bucket will be returned. For the specific error cause, see Put Bucket ACL according to the returned error code.
For more information on COS error codes or the complete list of product errors, please refer to the Error Codes document.
Practical Case
Request
PUT / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Thu, 12 Jan 2016 19:12:22 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484708728;32557604728&q-key-time=1484708728;32557604728&q-header-list=host&q-url-param-list=&q-signature=b394a86624cbcc705b11bc6fc505843c5e2dd9c9
Response
HTTP /1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Thu, 12 Jan 2016 19:12:22 GMT
x-cos-request-id: NTg3ZWRiODJfOWIxZjRlXzZmNDBfMTUz