tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

PUT Bucket

Last updated: 2024-03-28 18:08:32

    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.
    

    Request

    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:
    In Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, <BucketName-APPID> is the bucket name followed by the APPID, such as examplebucket-1250000000 (see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions), and <Region> is a COS region (see Regions and Access Endpoints).
    Authorization: Auth String (See Request Signature for details.)

    Request parameters

    This API has no request parameter.

    Request headers

    In addition to common request headers, this API also supports the following request headers. For more information about common request headers, please see Common Request Headers.
    Header
    Description
    Type
    Required
    x-cos-tagging
    Adds up to 50 tags to a bucket during bucket creation, such as key1=value1&key2=value2.
    string
    No
    ACL-related headers
    You can configure an access control list (ACL) for a bucket by specifying the following request headers during bucket creation:
    Header
    Description
    Type
    Required
    x-cos-acl
    Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private (default) and public-read, please see the Preset ACL section in ACL Overview.
    Enum
    No
    x-cos-grant-read
    Grants a user permission to read the bucket in the format of id="[OwnerUin]" (e.g., id="100000000001"). You can use a comma (,) to separate multiple users, for example, id="100000000001",id="100000000002".
    string
    No
    x-cos-grant-write
    Grants a user permission to write to the bucket in the format of id="[OwnerUin]" (e.g., id="100000000001"). You can use a comma (,) to separate multiple users, for example, id="100000000001",id="100000000002".
    string
    No
    x-cos-grant-read-acp
    Grants a user permission to read the ACL and policies of the bucket in the format of id="[OwnerUin]" (e.g., id="100000000001"). You can use a comma (,) to separate multiple users, for example, id="100000000001",id="100000000002".
    string
    No
    x-cos-grant-write-acp
    Grants a user permission to write to the ACL and policies of a bucket in the format of id="[OwnerUin]" (e.g., id="100000000001"). You can use a comma (,) to separate multiple users, for example, id="100000000001",id="100000000002".
    string
    No
    x-cos-grant-full-control
    Grants a user full permission to operate on the bucket in the format of id="[OwnerUin]" (e.g., id="100000000001"). You can use a comma (,) to separate multiple users, for example, id="100000000001",id="100000000002".
    string
    No

    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
    Type
    Required
    CreateBucketConfiguration
    None
    All configurations of the PUT Bucket request
    Container
    No
    CreateBucketConfiguration has the following sub-nodes:
    Node Name (Keyword)
    Parent Node
    Description
    Type
    Required
    BucketAZConfig
    CreateBucketConfiguration
    AZ configuration of the bucket. To create an MAZ bucket, specify MAZ.
    string
    Yes

    Response

    Response headers

    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

    Example 1: simple use case (OAZ bucket)

    Request

    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****&q-sign-time=1558882298;1558889498&q-key-time=1558882298;1558889498&q-header-list=content-length;date;host&q-url-param-list=&q-signature=c25fd640274a6da2318935ceebfbcfba4598****
    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****

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

    Request

    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****&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****
    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

    Request

    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****&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****
    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 sample request is used to create the bucket examplebucket-1250000000 in Beijing region and add two tags <a,a> and <b,b> to the bucket.

    Request

    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******&q-sign-time=1667446950;1668447000&q-key-time=1667446950;1668447000&q-url-param-list=&q-header-list=host;x-cos-tagging&q-signature=6d0ef3446f29aca9f28f66a031******

    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********
    
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy