Overview

OBS provides bucket inventories to facilitate your management of objects in a bucket. You can configure bucket inventories to periodically list objects in a bucket. During the listing of objects, object metadata is saved in a CSV file, which is uploaded to the specified bucket.

When configuring a bucket inventory, you can specify the filter criteria (by object name prefix) of objects, set the inventory generation interval (daily or weekly), and choose whether to list all versions of objects. In addition, you can also specify the content of object metadata to be listed by the inventory, including the object size, modification time, and storage class.

You can configure multiple inventories for a bucket, but the object name prefixes specified in these inventories cannot overlap. For example, if an inventory has been configured to filter objects by the name prefix of a, the object name prefix ab cannot be used as the filter criteria of another inventory for the bucket.

Use Restrictions

• Only OBS 3.0 buckets support this function. However, this restriction does not apply to the destination bucket where inventory files are saved.
• The source bucket for which an inventory is configured and the destination bucket where inventory files are saved must belong to the same tenant and reside in the same region.
• Inventory files are in CSV format.
• If a bucket has enabled the KMS encryption function, it cannot be used as the destination bucket for saving inventory files.
• Inventory files are delivered to the destination bucket by an OBS system user. Therefore, you need to authorize the system user the permission to write the destination bucket.

How to Configure a Bucket Inventory

Configuring a Bucket Inventory

You use OBS Console or call the API to configure a bucket inventory. If you configure a bucket inventory on OBS Console, a bucket policy with the required permission configuration is automatically generated for the destination bucket. If you call the API to configure the bucket inventory, you need to manually configure the bucket policy for the destination bucket.

1. Add a bucket policy for the destination bucket.

   A bucket policy must be configured for the destination bucket, to grant the OBS system users the permission to write objects to the destination bucket. The format of the bucket policy is as follows. Replace destbucket with the actual name of the destination bucket.

   {
   	"Statement": [
   		{
   			"Effect": "Allow",
   			"Sid": "1",
   			"Principal": {"Service": "obs"},
                           "Resource": ["destbucket/*"],
   			"Action": ["PutObject"]
   		}
   	]
   }

2. Configure a bucket inventory.

   For details about how to configure a bucket list by calling the API, see descriptions about configuring bucket inventories in the OBS API Reference.

Content in an Inventory File

The content in an inventory file can be configured when creating the inventory. For details about all possible fields, see Table 1.

Inventory File Name

The name of an inventory file is in the following format:

destinationPrefix/sourceBucketName/inventoryId/yyyy-MM-dd'T'HH-mm'Z'/files/UUID_index.csv

Manifest File

If a source bucket contains a large number of objects, multiple inventory files may be generated under one inventory rule. After complete inventory files are generated, a manifest.json file is generated. summarizing information about all the generated inventory files. See information details as follows:

• sourceBucket: name of the source bucket
• destinationBucket: name of the destination bucket
• version: version of the inventory
• fileFormat: format of inventory files
• fileSchema: object metadata fields contained in the inventory files
• files: list of all inventory files
• key: inventory file name
• size: size of an inventory file, in bytes
• inventoriedRecord: number of records contained in an inventory file

{
        "sourceBucket":"user001",
        "destinationBucket":"bucket001",
        "version":"2019-01-03",
        "fileFormat":"CSV",
        "fileSchema":"Bucket,Key,Size,LastModifiedDate,ETag,StorageClass,IsMultipartUploaded,ReplicationStatus,EncryptionStatus",
        "files":[
                {
                        "key":"inventory/user001/test_id/2019-01-03T12-28Z/files/0000016813AF58E66806C1E2D7F15155_1.csv",
                        "size":6705647390,
                        "inventoriedRecord":70585762,
                }
        ]
}

The name of a manifest file is as follows. The meanings of the fields are as follows:

destinationPrefix/sourceBucketName/inventoryId/yyyy-MM-dd'T'HH-mm'Z'/manifest.json

How Is a User Notified When the Generation of Inventory Files Complete?

You can enable SMN (the message notification service) for the destination bucket. By doing so, you can receive SMS messages or emails every time when inventory files and the manifest file are generated. For more information about SMN, see Event notification.

The following is a simple example of SMN configuration. destinationPrefix/sourceBucketName indicates the prefix of the manifest file. destinationPrefix is the configured name prefix for inventory files, and sourceBucketName is the source bucket for which the inventory file is configured. The manifest.json is the suffix of the manifest file.

<NotificationConfiguration>
  <TopicConfiguration>
    <Id>01</Id>
    <Filter>
      <Object>
        <FilterRule>
          <Name>prefix</Name>
          <Value>destination-prefix/source-bucket</Value>
        </FilterRule>
        <FilterRule>
          <Name>suffix</Name>
          <Value>manifest.json</Value>
        </FilterRule>
      </Object>
    </Filter>
    <Topic>urn:smn:southchina:11aa22bb:notification</Topic>
    <Event>ObjectCreated:Put</Event>
  </TopicConfiguration>
</NotificationConfiguration>