CreateBucketMetadataConfiguration

Updated at:

Call CreateBucketMetadataConfiguration to enable the metadata management feature for a general-purpose bucket. This operation can configure the record expiration and encryption settings of the journal table and, at the same time, specify whether to enable the live inventory table.

Permissions

By default, an Alibaba Cloud account has full permissions. A RAM user or RAM role under an Alibaba Cloud account has no permissions by default; the account or an account administrator must grant the required permissions.

API

Action

Description

CreateBucketMetadataConfiguration

oss:CreateBucketMetadataTableConfiguration

Enables the metadata management feature.

When you enable the feature, OSS must create and manage the underlying table resources, so the following dependent permissions are also required:

  • osstables:CreateTableBucket

  • osstables:CreateNamespace

  • osstables:GetTable

  • osstables:CreateTable

  • osstables:PutTablePolicy

  • osstables:PutTableEncryption

  • kms:DescribeKey

Request syntax

POST /?metadataConfiguration HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Content-Length: ContentLength
Content-MD5: MD5Value
Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>
<MetadataConfiguration>
   <JournalTableConfiguration>
      <RecordExpiration>
         <Expiration>ENABLED</Expiration>
         <Days>7</Days>
      </RecordExpiration>
      <EncryptionConfiguration>
         <SseAlgorithm>SSE-KMS</SseAlgorithm>
         <KmsKeyArn>acs:kms:cn-hangzhou:123456789012:key/key-id</KmsKeyArn>
      </EncryptionConfiguration>
   </JournalTableConfiguration>
   <InventoryTableConfiguration>
      <ConfigurationState>ENABLED</ConfigurationState>
      <EncryptionConfiguration>
         <SseAlgorithm>SSE-KMS</SseAlgorithm>
         <KmsKeyArn>acs:kms:cn-hangzhou:123456789012:key/key-id</KmsKeyArn>
      </EncryptionConfiguration>
   </InventoryTableConfiguration>
</MetadataConfiguration>

Request headers

Name

Type

Required

Description

Content-MD5

String

No

The MD5 hash of the request body.

x-oss-expected-bucket-owner

String

No

The expected account ID of the bucket owner.

Request elements

Name

Type

Required

Description

MetadataConfiguration

Container

Yes

The root node of the metadata management configuration.

Parent node: none

JournalTableConfiguration

Container

Yes

The configuration of the journal table.

Parent node: MetadataConfiguration

JournalTableConfiguration.RecordExpiration

Container

Yes

The record expiration configuration of the journal table.

Parent node: JournalTableConfiguration

JournalTableConfiguration.RecordExpiration.Expiration

String

Yes

Whether record expiration is enabled. Valid values: ENABLED, DISABLED.

Parent node: RecordExpiration

JournalTableConfiguration.RecordExpiration.Days

Integer

Conditionally required

The number of days after which records expire, as a positive integer. Required when Expiration is ENABLED.

Parent node: RecordExpiration

JournalTableConfiguration.EncryptionConfiguration

Container

No

The encryption configuration of the journal table.

Parent node: JournalTableConfiguration

JournalTableConfiguration.EncryptionConfiguration.SseAlgorithm

String

Conditionally required

The encryption algorithm. Required when EncryptionConfiguration is specified.

Parent node: EncryptionConfiguration

JournalTableConfiguration.EncryptionConfiguration.KmsKeyArn

String

Conditionally required

The ARN of the KMS key. Required when SseAlgorithm is SSE-KMS.

Parent node: EncryptionConfiguration

InventoryTableConfiguration

Container

No

The configuration of the live inventory table, which can be enabled at the same time as the feature.

Parent node: MetadataConfiguration

InventoryTableConfiguration.ConfigurationState

String

Conditionally required

Whether the live inventory table is enabled. Required when InventoryTableConfiguration is specified. Valid values: ENABLED, DISABLED.

Parent node: InventoryTableConfiguration

InventoryTableConfiguration.EncryptionConfiguration

Container

No

The encryption configuration of the live inventory table.

Parent node: InventoryTableConfiguration

Response

If the operation succeeds, HTTP status code 200 is returned with an empty response body.

Response headers

This operation uses only common response headers. For more information, see Common response headers.

Examples

  • Sample request

    POST /?metadataConfiguration HTTP/1.1
    Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
    Date: Wed, 16 Sep 2026 12:00:00 GMT
    Authorization: SignatureValue
    
    <?xml version="1.0" encoding="UTF-8"?>
    <MetadataConfiguration>
       <JournalTableConfiguration>
          <RecordExpiration>
             <Expiration>ENABLED</Expiration>
             <Days>7</Days>
          </RecordExpiration>
       </JournalTableConfiguration>
       <InventoryTableConfiguration>
          <ConfigurationState>ENABLED</ConfigurationState>
       </InventoryTableConfiguration>
    </MetadataConfiguration>
  • Sample response

    HTTP/1.1 200 OK

SDK

The SDKs for CreateBucketMetadataConfiguration in each language are as follows:

ossutil command-line interface

For the ossutil command that corresponds to CreateBucketMetadataConfiguration, see create-bucket-metadata-configuration.