Object Storage Service:PutBucket

API

Action

Definition

PutBucket

oss:PutBucket

Creates a bucket.

oss:PutBucketAcl

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

Header

Type

Required

Example

Description

x-oss-acl

String

No

private

The ACL of the bucket. Valid values:

• public-read-write: public-read-write

• public-read: public-read

• private (default): private

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 in the Resource Management console or by calling the ListResourceGroups operation. For more information, see View basic information of a resource group and ListResourceGroups.

x-oss-bucket-tagging

String

No

k1=v1&k2=v2

The tags of the bucket.

x-oss-hns-status

String

No

disabled

Specifies whether to enable the hierarchical namespace feature for the bucket.

You can enable the hierarchical namespace feature only when you create a bucket. You cannot change the hierarchical namespace status of an existing bucket.

• enabled: Enables the feature.

  After you enable the hierarchical namespace feature for a bucket, you can perform folder operations in the bucket, such as creating, deleting, and renaming folders.

• disabled (default): Disables the feature.

x-oss-server-side-encryption

String

No

AES256

The default server-side encryption method.

Valid values: KMS, AES256

A small fee is charged for calling KMS API operations when you use KMS keys. For more information, see KMS pricing.

When you use cross-region replication, if the destination bucket has default server-side encryption enabled and the replication rule has ReplicaCMKID configured, the following cases apply:

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

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

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

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

String

No

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

The ID of the KMS key. This header is required when x-oss-server-side-encryption is set to KMS and you want to use a specified key for encryption. In other cases, this header must be empty.

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

Name

Type

Required

Example

Description

StorageClass

String

No

Standard

The storage class of the bucket. Valid values:

• Standard (default): Standard

• 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 redundant 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.

• ZRS

  Zone-redundant storage (ZRS) uses a data redundancy mechanism across multiple zones. ZRS stores redundant copies of your data across multiple zones in the same region. This ensures that your data remains accessible even if a zone becomes unavailable.

Parent node: CreateBucketConfiguration

Child nodes: none

Header

Type

Example

Description

Location

String

/oss-example

The address of the bucket. It consists of a forward slash (/) and the bucket name.

Default value: none

Error code

HTTP status code

Description

InvalidBucketName

400

The specified bucket name does not follow the naming conventions.

AccessDenied

403

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 a region.

BucketAlreadyExists

409

• The request to create a Bucket with the same name as a deleted Bucket does not meet the time requirement.

  You try to create a bucket with the same name as a bucket that was recently deleted. After you delete a bucket, you must wait for several hours, typically 4 to 8 hours, before you can create another bucket with the same name.

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

  Only an Alibaba Cloud account can recreate 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.

• You try to change the hierarchical namespace status of an existing bucket. You can enable the hierarchical namespace feature only when you create a bucket.