Todos os produtos
Search

Este produto

    Object Storage Service:PutBucket

    Central de documentação

    Object Storage Service:PutBucket

    Última atualização: Jun 23, 2026

    The PutBucket operation creates a bucket.

    Usage notes

    • The same Alibaba Cloud account can create at most 100 buckets in the same region.

    • Each region maps to a specific endpoint. Region-to-endpoint mappings are listed in Endpoints and data centers.

    • If you call PutBucket multiple times on the same bucket, the first call creates it and subsequent calls modify its metadata (such as ACL). Repeated calls may overwrite existing metadata. Proceed with caution.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    PutBucket

    oss:PutBucket

    Creates a bucket.

    oss:PutBucketAcl

    After creating a bucket, this permission is required to modify the bucket ACL.

    Request Syntax

    PUT / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
x-oss-acl: Permission
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

    Request Headers

    Name

    Type

    Required

    Example

    Description

    x-oss-acl

    String

    No

    private

    The access control list (ACL) of the bucket. Valid values:

    • public-read-write: Public read and write

    • public-read: Public read

    • private (default): Private

    Bucket ACL permissions are described in Configure bucket ACL.

    x-oss-resource-group-id

    String

    No

    rg-aek27tc****

    The resource group ID.

    • If specified, the bucket is created in this resource group.

      If set to rg-default-id, the bucket belongs to the default resource group.

    • If omitted, the bucket belongs to the default resource group.

    You can obtain the resource group ID through the Resource Management console or the ListResourceGroups API. For specific operations, see View a resource group and ListResourceGroups.

    x-oss-bucket-tagging

    String

    No

    k1=v1&k2=v2

    Bucket tags.

    x-oss-hns-status

    String

    No

    disabled

    Whether to enable hierarchical namespace for the bucket.

    Hierarchical namespace can only be set during bucket creation and cannot be changed afterward.

    • enabled: Enabled

      Enables directory operations such as creating, deleting, and renaming directories in the bucket.

    • disabled (default): Disabled

    x-oss-server-side-encryption

    String

    No

    AES256

    The default server-side encryption method.

    Valid values: KMS, AES256

    null

    In OSS ON Cloud Box scenarios, only AES256 is supported.

    When you use KMS key features, a small amount of KMS key API call fees will be incurred. For more information about fees, see KMS billing standards.

    During cross-region replication, if the target bucket has default encryption enabled and ReplicaCMKID is configured:

    • Unencrypted source objects are encrypted using the target bucket's default encryption method.

    • Objects encrypted with SSE-KMS or SSE-OSS retain their original encryption method.

    For more information, see Cross-region replication combined with server-side encryption.

    x-oss-server-side-encryption-key-id

    String

    No

    9468da86-3509-4f8d-a61e-6eab1eac****

    Required when SSEAlgorithm is KMS and a specific key is used. Must be empty otherwise.

    If you use OSS on CloudBox, this parameter is not supported.

    This operation also requires common request headers. For more information, see Common request headers.

    Request Elements

    Name

    Type

    Required

    Example Value

    Description

    StorageClass

    String

    No

    Standard

    The storage class of the bucket. Valid values:

    • Standard (default): Standard storage

    • IA: Infrequent Access

    • Archive: Archive Storage

    • ColdArchive: Cold Archive Storage

    • DeepColdArchive: Deep Cold Archive Storage

    Parent node: CreateBucketConfiguration

    Child nodes: None

    DataRedundancyType

    String

    No

    LRS

    The data redundancy type of the bucket. Valid values:

    • LRS (default)

      Locally redundant storage (LRS) stores data redundantly across different storage devices within the same availability zone, ensuring accessibility even if two devices fail simultaneously.

    • ZRS

      Zone-redundant storage (ZRS)ZRS stores multiple copies of your data across multiple zones in the same region. Your data is still accessible even if a zone becomes unavailable.

    Parent node: CreateBucketConfiguration

    Child nodes: None

    Response headers

    Name

    Type

    Sample value

    Description

    Location

    String

    /oss-example

    The bucket path, in the format /.

    Default: None

    This operation also returns common response headers. For more information, see Common response headers.

    Examples

    • Create a bucket in the default resource group

      PUT / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
x-oss-acl: private
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
    <DataRedundancyType>LRS</DataRedundancyType>    
</CreateBucketConfiguration>

    • Response example

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    • Create a bucket in a specified resource group

      Request example

      PUT / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
x-oss-acl: private
x-oss-resource-group-id: rg-aek27tc********
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

      Response example

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    SDK

    SDKs for the PutBucket operation:

    Command-line tool ossutil

    For the ossutil command that corresponds to the PutBucket operation, see put-bucket.

    Error codes

    Error code

    HTTP status code

    Description

    InvalidBucketName

    400

    The specified bucket name does not comply with naming conventions.

    AccessDenied

    403

    This error may be returned for the following reasons:

    • Authentication information was not included in the PutBucket request.

    • Insufficient permissions.

    TooManyBuckets

    400

    Bucket limit exceeded. An Alibaba Cloud account can create a maximum of 100 buckets per region.

    BucketAlreadyExists

    409

    • The required wait period after bucket deletion has not elapsed.

      After deleting a bucket, wait typically 4-8 hours before creating a bucket with the same name.

    • A RAM user or STS token called PutBucket on an existing bucket.

      Only Alibaba Cloud accounts can call PutBucket repeatedly on existing buckets.

    • The caller lacks oss:PutBucketAcl permission. Grant this permission through a bucket policy or RAM policy.

    • Attempted to modify hierarchical namespace on an existing bucket. This can only be set during bucket creation.