DocsICP FilingConsole
官方文档
首页

PutBucket

更新时间：
复制 MD 格式
产品详情
我的收藏

Call the PutBucket operation to create a bucket.

Notes

  • An Alibaba Cloud account can create a maximum of 100 buckets in each region.

  • Each region has a corresponding endpoint. For more information about the endpoints for each region, see Endpoints.

  • If you call the PutBucket operation multiple times for the same bucket, the first call creates the bucket and subsequent calls modify its metadata, such as the bucket ACL. This can cause the bucket metadata to be overwritten. Proceed with caution.

  • From 10:00 (UTC+8) on October 13, 2025, OSS will implement a phased adjustment across all regions to enable Block Public Access by default for new buckets created using the API, OSS SDKs, or ossutil. For details about the exact times when the adjustment will take effect in each region, see announcement. Once Block Public Access is enabled, you cannot configure public access permissions, including public ACLs (public read and public read/write) and bucket policies that allows public access. You can disable this feature after the bucket is created if your business requires public access.

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>

  • 当您在OSS ON云盒中调用该接口时，您需要将Host替换为云盒Endpoint。更多信息，请参见云盒Endpoint。

  • When you call this operation to create an Anywhere Bucket, you must replace the public endpoint in the Host, such as oss-cn-hangzhou.aliyuncs.com, with oss-rg-china-mainland.aliyuncs.com. For more information, see Bucket region attributes.

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: Grants public read and write permissions.

  • public-read: Public Read

  • private (default)

For more information about bucket ACLs, see Set bucket ACLs.

x-oss-resource-group-id

String

No

rg-aek27tc****

The ID of the resource group.

  • If you include this header in the request and specify a resource group ID, the created bucket belongs to the specified resource group.

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

  • If you do not include this header in the request, the created bucket belongs to the default resource group.

You can obtain the resource group ID on the Resource Management console or by calling the ListResourceGroups operation. For more information, see View resource groups and ListResourceGroups.

Note

Resource groups cannot be configured when you create an Anywhere Bucket.

x-oss-bucket-tagging

String

No

k1=v1&k2=v2

Specifies the bucket tags.

x-oss-server-side-encryption

String

No

AES256

Sets the default server-side encryption method.

Valid values: KMS, AES256, and SM4

Note

In OSS ON CloudBox scenarios, only AES256 is supported.

Using the KMS feature incurs a small fee for KMS API calls. For more information about the pricing, see KMS pricing.

During cross-region replication, if the destination bucket has default server-side encryption enabled and the replication rule is configured with a ReplicaCMKID, the following situations apply:

  • If an object in the source bucket is not encrypted, the object is encrypted using the default encryption method of the destination bucket after it is replicated.

  • If an object in the source bucket is encrypted using SSE-KMS or SSE-OSS, the object retains its original encryption method in the destination bucket.

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

x-oss-server-side-data-encryption

String

No

SM4

Specifies the encryption algorithm for the object. If you do not specify this header, the AES256 encryption algorithm is used. This header is valid only when x-oss-server-side-encryption is set to KMS.

Valid value: SM4

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

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

String

No

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

The ID of the KMS key. This header is required only when x-oss-server-side-encryption is set to KMS. In other cases, this header must be empty.

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

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

Request elements

Name

Type

Required

Example

Description

StorageClass

String

No

Standard

The storage class of the bucket. Valid values:

  • Standard (default)

    Note

    • When you create an Anywhere Bucket, only the Standard storage class is supported.

    • In OSS ON CloudBox scenarios, only the Standard storage class is supported.

  • IA: Infrequent Access

  • Archive: Archive Storage

  • ColdArchive: Cold Archive

  • DeepColdArchive: Deep Cold Archive

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 copies of your data on different storage devices in the same zone. This ensures data durability and availability even if two storage devices are damaged at the same time.

    Note

    When you create an Anywhere Bucket, only the LRS type is supported.

  • ZRS

    Zone-redundant storage (ZRS) uses a data redundancy mechanism within multiple zones. ZRS stores the data of an object across multiple zones in the same region. If a zone becomes unavailable, you can still access the data.

Note

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

Parent node: CreateBucketConfiguration

Child nodes: None

Response headers

Name

Type

Example

Description

Location

String

/oss-example

The address of the bucket. The value is a forward slash (/) followed by the bucket name.

Default value: None

The response also includes 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>

  • Sample response

    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 specific resource group

    Sample request

    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>

    Sample response

    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

You can call the PutBucket operation using the OSS SDKs for the following programming languages:

ossutil command-line tool

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

Error codes

Error code

HTTP status code

Description

InvalidBucketName

400

The bucket name does not comply with the naming conventions.

AccessDenied

403

The following are possible causes of the error:

  • User authentication information is not included in the PutBucket request.

  • You do not have the required permissions.

TooManyBuckets

400

The number of created buckets exceeds the upper limit. An Alibaba Cloud account can create a maximum of 100 buckets in the same region.

BucketAlreadyExists

409

  • If a bucket has been deleted, the time requirement for creating a bucket with the same name is not met.

    You attempt to create a bucket with a name that was used by a bucket that was recently deleted. After a bucket is deleted, you must wait for several hours (typically 4 to 8 hours) before you can create a bucket with the same name.

  • You call the PutBucket operation using methods such as a RAM user or STS to create a bucket with the same name as an existing bucket.

    Only the original Alibaba Cloud account can re-create a bucket with the same name.

  • You do not have the permissions to call the PutBucketAcl operation. Make sure that the caller is granted the oss:PutBucketAcl permission using a bucket policy or a RAM policy.

Previous：Basic operationsNext：DeleteBucket