Help & Documentation>Cloud Object Storage>API Documentation>Bucket APIs>Basic Operations>PUT Bucket

PUT Bucket

Last updated: 2023-09-19 15:52:35

On this page:

Feature Overview

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.
Note
If no access permission is specified for a bucket when it is created, private (private read/write) will be used by default.
To create an MAZ bucket, you should indicate the bucket configuration through the request body; otherwise, you don't need to pass in the request body.



Requests

Sample Request

Sample 1
PUT / HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Length: 0
Authorization: Auth String
Sample 2
PUT / HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Request Body]
Note
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, where <BucketName-APPID> is the bucket name with the APPID suffix, such as examplebucket-1250000000. You can refer to the Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Convention documentation. <Region> represents the available regions for COS, which can be found in the Regions and Access Domain Names documentation.
Authorization: Auth String (For more information, see Request Signature.)

Request Parameters

This API has no request parameter.

Request Header

In addition to common request headers, this API also supports the following request headers. For more information on the common request header, see Common Request Headers.
Name
Description
Local Disk Types
Required
x-cos-tagging
Adds up to 50 tags to a bucket during bucket creation, such as key1=value1&key2=value2.
string
Not required
ACL-related headers
You can configure an access control list (ACL) for a bucket by specifying the following request headers during bucket creation:
Name
Description
Local Disk Types
Required
x-cos-acl
Defines the Access Control List (ACL) attribute for the bucket. For enumeration values, refer to the Preset ACL section in the ACL Overview document, such as private, public-read, etc. The default value is private.
Enum
Not required
x-cos-grant-read
Grants the authorized user read access to the bucket, with the format id="[OwnerUin]", such as id="100000000001". Multiple authorized users can be separated by commas (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-write
Grants the authorized user write access to the bucket, with the format id="[OwnerUin]", such as id="100000000001". Multiple authorized users can be separated by commas (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-read-acp
Grants the authorized user permission to read the Access Control List (ACL) and bucket policy (Policy) of the bucket, with the format id="[OwnerUin]", such as id="100000000001". Multiple authorized users can be separated by commas (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-write-acp
Grants the authorized user permission to write the Access Control List (ACL) and bucket policy (Policy) of the bucket, with the format id="[OwnerUin]", such as id="100000000001". Multiple authorized users can be separated by commas (,), such as id="100000000001",id="100000000002".
string
Not required
x-cos-grant-full-control
Grants the authorized user full access to the bucket, with the format id="[OwnerUin]", such as id="100000000001". Multiple authorized users can be separated by commas (,), such as id="100000000001",id="100000000002".
string
Not required

Request Body

Submit the application/xml request data only when you need to create an MAZ bucket, which includes the configuration information for bucket creation; otherwise, you don't need to pass in the request body.
<CreateBucketConfiguration>
    <BucketAZConfig>string</BucketAZConfig>
</CreateBucketConfiguration>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Required
CreateBucketConfiguration
-
All configurations of the PUT Bucket request
Container
Not required
CreateBucketConfiguration has the following sub-nodes:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Required
BucketAZConfig
CreateBucketConfiguration
AZ configuration of the bucket. To create an MAZ bucket, specify MAZ.
string
Required

Response

Response Header

This API only returns Common Response Headers.

Response Body

The response body of this API is empty.

Error Codes

This API returns common error responses and error codes. For more information, see Error Codes.

Examples

Sample 1: Simple use case (OAZ bucket)

Requests

PUT / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sun, 26 May 2019 14:51:38 GMT
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO<1>**&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=c25fd640274a6da2318935ceebfbcfba4598</1>**
Connection: close

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Sun, 26 May 2019 14:51:37 GMT
Server: tencent-cos
x-cos-request-id: NWNlYWE3ZjlfZDQyNzVkNjRfMzg1N18yNzFh****

Sample 2: Setting public-read and granting a user permissions to write to the bucket and read the bucket ACL and policies

Requests

PUT / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 14 Jun 2019 13:48:59 GMT
x-cos-acl: public-read
x-cos-grant-write: id="100000000002"
x-cos-grant-read-acp: id="100000000002"
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO<1>**&q-sign-time=1560520139;1560527339&q-key-time=1560520139;1560527339&q-header-list=content-length;date;host;x-cos-acl;x-cos-grant-read-acp;x-cos-grant-write&q-url-param-list=&q-signature=df03e7917270e0bf2b679bc6f99793bd0c63</1>**
Connection: close

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Fri, 14 Jun 2019 13:49:00 GMT
Server: tencent-cos
x-cos-request-id: NWQwM2E1Y2NfZjBhODBiMDlfOTM1YV83NDRi****

Sample 3: Creating an MAZ bucket

Requests

PUT / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 04 Jun 2020 06:06:09 GMT
Content-Type: application/xml
Content-Length: 96
Content-MD5: R1ES/YbddhKJK/wcN+f4yg==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO<1>**&q-sign-time=1591250769;1591257969&q-key-time=1591250769;1591257969&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=28db662452fcdf8f004fc578f1c3fccbfedd</1>**
Connection: close

<CreateBucketConfiguration>
    <BucketAZConfig>MAZ</BucketAZConfig>
</CreateBucketConfiguration>

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Thu, 04 Jun 2020 06:06:10 GMT
Server: tencent-cos
x-cos-request-id: NWVkODhmNTFfM2JiODJhMDlfMjg4NmFfMzA5ZmE2****

Sample 4: Creating a bucket and adding tags

The following request example creates a bucket examplebucket-1250000000 in the Beijing region and adds two bucket tags <a,a> and <b,b>.

Requests

PUT / HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
x-cos-tagging: a=a&b=b
Authorization: q-sign-algorithm=sha1&q-ak=AKIDYv3vWrwkHXVDf<1>*</1>*&q-sign-time=1667446950;1668447000&q-key-time=1667446950;1668447000&q-url-param-list=&q-header-list=host;x-cos-tagging&q-signature=6d0ef3446f29aca9f28f66a031<3>*</3>*

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Thu, 03 Nov 2022 03:43:30 GMT
Server: tencent-cos
x-cos-request-id: NjM2MzM4ZTJfZDRiNTE0M<1>*</1>***

中国站 - English