Use bucket inventory

更新时间:
复制 MD 格式

For buckets with millions or even billions of objects, listing them with the ListObjects API operation is inefficient and costly. The bucket inventory feature manages objects at this scale by asynchronously and periodically scanning a bucket to generate an inventory file with specified object metadata, such as object size and storage class.

Availability

  • The inventory feature is available only for buckets in a specific region.

  • To enable the incremental inventory feature, contact technical support.

Use cases

OSS provides full and incremental inventories. A full inventory is a snapshot of all existing objects in a bucket at a specific point in time, while an incremental inventory records the file metadata of objects that are added or modified within a specified period. You can configure both inventory types to generate inventory files and deliver them to a specified bucket. You can configure a full inventory to run once per cycle, while incremental inventory files are typically generated every 10 minutes. The following are the use cases for full and incremental inventory files:

  • One-time data analysis and statistics: If you only need to analyze historical objects, you can configure a full inventory rule to generate a single list of file metadata for offline data analysis.

  • Continuous data analysis and statistics: If you need to analyze historical objects and track subsequent changes, you can use both full and incremental inventories to build a unified metadata table. For example, you can write all existing and incremental metadata into your own table and use your own Spark cluster to retrieve, query, and analyze the metadata.

How it works

  • Full inventory: Generates a complete snapshot of the objects in a bucket periodically (daily, weekly, or monthly). The workflow is as follows:

    • Obtain permissions: OSS assumes a pre-authorized RAM role to scan the source bucket and write inventory reports to the destination bucket.

    • Scan objects: OSS scans objects in the source bucket that match the inventory rule's filter criteria, such as object prefix, version status, creation time, or size.

    • Generate inventory report: OSS aggregates the scan results into a Gzip-compressed CSV inventory report and writes it to the destination bucket.

  • Incremental inventory: Generated approximately every 10 minutes, it captures all object change events (such as creations, metadata updates, and deletions). The workflow is as follows:

    • Obtain permissions: OSS assumes a pre-authorized RAM role to scan the source bucket logs and write inventory reports to the destination bucket.

    • Scan objects: OSS scans records in the incremental logs that match the inventory rule's filter criteria, such as the object prefix.

    • Generate inventory report: OSS uses backend partitioning to aggregate the scan results and writes the inventory report to the destination bucket in CSV format.

After you create an inventory rule, OSS automatically runs the inventory task periodically. The task runs asynchronously and does not affect normal access to the bucket.

Create and authorize a service role

The OSS inventory service must assume a RAM role to obtain permissions to read from the source bucket and write to the destination bucket. To ensure account security, follow the principle of least privilege and create a dedicated service role for the inventory feature.

When you quickly configure an inventory on the console, the system prompts you to automatically create a role named AliyunOSSRole. You can use this default role without creating a service role. However, this role grants full management permissions on all buckets in your Alibaba Cloud account. For production environments, we recommend against using AliyunOSSRole.

Follow these steps to manually create a least-privilege role:

(Optional) Grant permissions to a RAM user to configure an inventory

An Alibaba Cloud account has all permissions by default. You can skip this step.

This step authorizes a RAM user, such as an operations administrator, to configure inventory rules. This step does not grant permissions to the inventory service itself. As a security best practice, an Alibaba Cloud account owner or an administrator with elevated permissions should create the required RAM role for the inventory service in advance. This allows a standard RAM user to configure the inventory by using this role, instead of needing the permissions to create it themselves.

To grant a RAM user permissions to create and manage inventory rules, grant the user a custom policy with the following permissions:

The oss:ListBuckets permission in the following policy is required only for operations in the console. This permission is not required when using tools such as SDKs or ossutil.
{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "oss:PutBucketInventory",
                "oss:GetBucketInventory",
                "oss:DeleteBucketInventory",
                "oss:ListBuckets",
                "ram:CreateRole",
                "ram:AttachPolicyToRole",
                "ram:GetRole",
                "ram:ListPoliciesForRole"
            ],
            "Resource": "*"
        }
    ],
    "Version": "1"
}

Tip: If the current RAM user already has the AliyunOSSFullAccess system policy, you only need to grant the following permissions for role management:

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ram:CreateRole",
                "ram:AttachPolicyToRole",
                "ram:GetRole",
                "ram:ListPoliciesForRole"
            ],
            "Resource": "*"
        }
    ],
    "Version": "1"
}
  1. Create a RAM role: Go to the Create RAM Role page. For Select Trusted Entity, select Alibaba Cloud Service. For Trusted Service, select OSS.

  2. Grant permissions to the RAM role to write to the destination bucket:

    1. On the Create Policy page, click the Script tab. Paste the following policy into the policy editor and replace dest-bucket with the name of your destination bucket.

      {
        "Version": "1",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": "oss:PutObject",
            "Resource": [
              "acs:oss:*:*:dest-bucket/*" 
            ]
          }
        ]
      }
    2. (Optional) Configure KMS encryption permissions: If the inventory report requires KMS encryption, you must also grant the RAM role the AliyunKMSCryptoUserAccess permission or more granular KMS permissions.

    3. On the Permissions page, click Add Permissions. For Principal, select the RAM role that you created. For Policy, select the policy that you just created, then click OK.

  3. Record the role ARN: On the Roles page, find the RAM role that you created. Go to the Basic Information page and copy the role ARN for use when creating the inventory rule. The ARN is in the format acs:ram::{source-account-id}:role/{role-name}.

Full list

An inventory periodically scans and exports a complete list of all objects in a bucket or under a specified prefix. Note:

  • Report snapshot: An inventory report provides a snapshot of objects when a scan task starts. Changes to objects, such as additions or deletions, during the scan might not be included in the current report.

  • The first inventory report runs immediately after you configure it. Subsequent reports run in batches during the early morning hours (UTC+8) daily, weekly, or monthly, depending on your configuration. Export latency depends on the number of objects and the task queue.

Configuration inventory rule

Console

  1. Sign in to the OSS Management Console.

  2. Navigate to the source bucket for which you want to generate an inventory. In the left navigation pane, choose Data Management > Bucket Inventory.

  3. On the Bucket Inventory page, click Create Inventory.

  4. In the Create Inventory panel, configure the following parameters:

    Parameter

    Description

    Status

    Select Start to enable the inventory task.

    Rule Name

    Specify a name for the inventory task. The name can contain only lowercase letters, digits, and hyphens (-). It cannot start or end with a hyphen (-).

    Store inventory report to

    The destination for the inventory reports. The destination bucket must be in the same region and belong to the same account as the source bucket.

    • To save the report to the exampledir1/ path in the examplebucket bucket, enter exampledir1/. If the specified path does not exist in the bucket, OSS creates it automatically.

    • If you leave this field empty, the report is saved to the root directory.

    Important

    If the OSS-HDFS service is enabled for a bucket, do not set the inventory report directory to .dlsdata/. This prevents interference with the service and avoids data contamination.

    Inventory file scan scope

    • Scan Entire Bucket: Scan all objects in the bucket.

    • Object Prefix: Scan only objects that match the specified prefix, such as exampledir1/.

    Encryption Method

    Specifies the encryption method for the inventory report.

    • None: No encryption.

    • AES256: Encrypts the report using AES256.

    • KMS: Encrypts the inventory file by using a KMS key. You can use an OSS-managed KMS key or create a KMS key in the same region as the destination bucket in the KMS console.

    Note

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

    Frequency

    The frequency at which OSS generates inventory reports. You can select Weekly, Daily, Monthly, or One-time Export. For buckets with over 10 billion objects, select Weekly to reduce costs and scanning overhead.

    Important

    The Monthly schedule is not supported in the following regions: China (Zhangjiakou), China (Zhongwei), US (Virginia), US (Silicon Valley), Mexico, France (Paris), China (Beijing) Finance, China (Shanghai) Finance, China (Shenzhen) Finance, China North 2 Ali Government Cloud 1

    Specified Date

    When you set the export cycle to Monthly, you can specify the day of the month on which to start the inventory task. The value must be an integer from 1 to 31.

    • If you select Unspecified Date, OSS exports the inventory on a fixed 30-day interval by default. The first scan starts on the day you configure the rule, and the inventory is exported every 30 days after that.

    • If you specify a day from 1 to 28, the inventory task starts on that day of each month.

    • If you specify a day from 29 to 31, the task starts on that day if it exists in the current month. If the day does not exist, the task starts on the last day of the month. For example, if you specify the 31st of each month, the inventory task for April starts on the 30th.

    Note

    The specified date is when the inventory task begins, not when the report is delivered. Report generation is an asynchronous task, and its completion time depends on the number of objects in the bucket. Delivery will occur after the specified date.

    Optional Fields

    The object information to include in the report:

    • System Metadata: Object Size, Storage Class, Last Modified Date, ETag, TransitionTime, Multipart Upload Status, Encryption Status, Object ACL, Object Type, CRC64, Last Accessed Time, and Last Accessed Timestamp.

      Note

      Last Accessed Time and Last Accessed Timestamp can be exported only when Access Tracking is enabled for the bucket. If Access Tracking is disabled, the values of these two fields are no longer meaningful and are usually displayed as null.

    • Custom Metadata: Number of Tags

    Advanced Filtering

    Important

    The following filter options are supported only in the China (Qingdao), China (Hohhot), and Germany (Frankfurt) regions.

    If you need to filter exported files based on conditions such as file size or storage class, turn on the Advanced Filtering switch.

    The supported filter options are described as follows:

    • Time Range: The start date and end date of the last modification for the objects to be exported. The time is accurate to the second.

    • Object Size Range: The minimum and maximum size of the objects to be exported.

      Important

      The minimum and maximum sizes must be greater than 0 B. The maximum size cannot exceed 48.8 TB.

    • Storage Class: The storage classes of the objects to be exported. You can choose to export objects of the Standard, Infrequent Access, Archive, Cold Archive, and Deep Cold Archive storage classes.

    Object Versions

    If versioning is enabled for the bucket, select Current Version or All Versions.

  5. Select I understand and agree to grant Alibaba Cloud OSS the permission to access Bucket resources, then click OK.

    Generating the inventory file may take some time if the bucket contains many objects. To learn how to check if the file is ready, see How do I determine whether an inventory file has been generated?.

SDK

import com.aliyun.oss.*;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;

public class Demo {

    public static void main(String[] args) throws Exception {
        // In this example, the endpoint of the China (Hangzhou) region is used. Specify your actual endpoint. 
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket. Example: examplebucket. 
        String bucketName = "examplebucket";
        // Specify the name of the bucket in which you want to store the generated inventory lists. 
        String destBucketName ="yourDestinationBucketName";
        // Specify the account ID granted by the bucket owner. 
        String accountId ="yourDestinationBucketAccountId";
        // Specify the name of the RAM role that is granted the permissions to read all objects in the bucket for which you want to configure the inventory and the permissions to write data to the bucket in which you want to store the generated inventory lists. 
        String roleArn ="yourDestinationBucketRoleArn";
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
        String region = "cn-hangzhou";

        // Create an OSS Client instance. 
        // Call the shutdown method to release associated resources when the OSS Client is no longer in use.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // Create an inventory. 
            InventoryConfiguration inventoryConfiguration = new InventoryConfiguration();

            // Specify the inventory name. 
            String inventoryId = "testid";
            inventoryConfiguration.setInventoryId(inventoryId);

            // Specify the object attributes that are included in inventory lists. 
            List<String> fields = new ArrayList<String>();
            fields.add(InventoryOptionalFields.Size);
            fields.add(InventoryOptionalFields.LastModifiedDate);
            fields.add(InventoryOptionalFields.IsMultipartUploaded);
            fields.add(InventoryOptionalFields.StorageClass);
            fields.add(InventoryOptionalFields.ETag);
            fields.add(InventoryOptionalFields.EncryptionStatus);
            inventoryConfiguration.setOptionalFields(fields);

            // Specify whether to generate inventory lists on a daily or weekly basis. The following code provides an example on how to generate the inventory lists on a weekly basis. Weekly indicates that the inventory lists are generated once a week and Daily indicates that the inventory lists are generated once a day. 
            inventoryConfiguration.setSchedule(new InventorySchedule().withFrequency(InventoryFrequency.Weekly));

            // Specify that the inventory lists include only the current version of objects. If you set the InventoryIncludedObjectVersions parameter to All, all versions of objects are included in the inventory lists. This configuration takes effect only when you enable versioning for the bucket. 
            inventoryConfiguration.setIncludedObjectVersions(InventoryIncludedObjectVersions.Current);

            // Specify whether the inventory is enabled. Valid values: true and false. Set the value to true to enable the inventory. Set the value to false to disable the inventory. 
            inventoryConfiguration.setEnabled(true);

            // Specify the rule used to filter the objects to include in the inventory lists. The following code provides an example on how to filter the objects by prefix. 
            InventoryFilter inventoryFilter = new InventoryFilter().withPrefix("obj-prefix");
            inventoryConfiguration.setInventoryFilter(inventoryFilter);

            // Specify the destination bucket in which you want to store the generated inventory lists. 
            InventoryOSSBucketDestination ossInvDest = new InventoryOSSBucketDestination();
            // Specify the prefix of the path in which you want to store the generated inventory lists. 
            ossInvDest.setPrefix("destination-prefix");
            // Specify the format of the inventory lists. 
            ossInvDest.setFormat(InventoryFormat.CSV);
            // Specify the ID of the account to which the destination bucket belongs. 
            ossInvDest.setAccountId(accountId);
            // Specify the role ARN of the destination bucket. 
            ossInvDest.setRoleArn(roleArn);
            // Specify the name of the destination bucket. 
            ossInvDest.setBucket(destBucketName);

            // The following code provides an example on how to encrypt the inventory lists by using customer master keys (CMKs) hosted in Key Management System (KMS). 
            // InventoryEncryption inventoryEncryption = new InventoryEncryption();
            // InventoryServerSideEncryptionKMS serverSideKmsEncryption = new InventoryServerSideEncryptionKMS().withKeyId("test-kms-id");
            // inventoryEncryption.setServerSideKmsEncryption(serverSideKmsEncryption);
            // ossInvDest.setEncryption(inventoryEncryption);

            // The following code provides an example on how to encrypt the inventory lists on the OSS server. 
            // InventoryEncryption inventoryEncryption = new InventoryEncryption();
            // inventoryEncryption.setServerSideOssEncryption(new InventoryServerSideEncryptionOSS());
            // ossInvDest.setEncryption(inventoryEncryption);

            // Specify the destination for the generated inventory lists. 
            InventoryDestination destination = new InventoryDestination();
            destination.setOssBucketDestination(ossInvDest);
            inventoryConfiguration.setDestination(destination);

            // Configure the inventory for the bucket. 
            ossClient.setBucketInventoryConfiguration(bucketName, inventoryConfiguration);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}
const OSS = require('ali-oss');

const client = new OSS({
  // The region where the bucket is located. Replace yourregion with the actual region. For example, if the bucket is in the China (Hangzhou) region, set this parameter to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run this sample code, make sure that you have configured the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // The bucket name.
  bucket: 'yourbucketname'
});

const inventory = {
  // The ID of the inventory configuration.
  id: 'default', 
  // Specifies whether to enable the inventory. Valid values: true and false.
  isEnabled: false, 
  // (Optional) The inventory filter. Specify a prefix for the objects to be inventoried.
  prefix: 'ttt',
  OSSBucketDestination: {
    // The format of the inventory report.
    format: 'CSV',
    // The account ID of the owner of the destination bucket.
    accountId: '<Your AccountId>', 
    // The name of the role for the destination bucket.
    rolename: 'AliyunOSSRole',
    // The name of the destination bucket.
    bucket: '<Your BucketName>',
    // (Optional) A prefix for the path where the inventory report is stored.
    prefix: '<Your Prefix>',
    // If you want to use server-side encryption with OSS-managed keys to encrypt the inventory report, see the following code.
    //encryption: {'SSE-OSS': ''},
    // If you want to use server-side encryption with KMS keys (SSE-KMS) to encrypt the inventory report, see the following code.
           /*
            encryption: {
      'SSE-KMS': {
        keyId: 'test-kms-id',
      };, 
    */
  },
  // The inventory generation schedule. Valid values: Daily and Weekly.
  frequency: 'Daily', 
  // The object versions to include in the inventory. If you set this parameter to Current, only the current version of objects is included.
  includedObjectVersions: 'All', 
  optionalFields: {
    // (Optional) The object attributes to include in the inventory report.
    field: ["Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus"]
  },
}

async function putInventory(){
  // The name of the bucket for which to add the inventory configuration.
  const bucket = '<Your BucketName>'; 
        try {
    await client.putBucketInventory(bucket, inventory);
    console.log('The inventory configuration was added.')
  } catch(err) {
    console.log('Failed to add the inventory configuration: ', err);
  }
}

putInventory()
import argparse
import alibabacloud_oss_v2 as oss

# Create a command line parameter parser and describe the purpose of the script. The example describes how to create an inventory for a bucket.
parser = argparse.ArgumentParser(description="put bucket inventory sample")

# Specify the command line parameters, including the required region, bucket name, endpoint, user ID, Alibaba Cloud Resource Name (ARN) of the RAM role, and inventory name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--user_id', help='User account ID.', required=True)
parser.add_argument('--arn', help='The Alibaba Cloud Resource Name (ARN) of the role that has the permissions to read all objects from the source bucket and write objects to the destination bucket. Format: `acs:ram::uid:role/rolename`.', required=True)
parser.add_argument('--inventory_id', help='The name of the inventory.', required=True)

def main():
    # Parse the command line parameters to obtain the values specified by the user.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configurations of the SDK to create a configuration object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region attribute of the configuration object based on the command line parameters specified by the user.
    cfg.region = args.region

    # If a custom endpoint is provided, modify the endpoint parameter in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding configurations to initialize the OSSClient instance and allow the instance to interact with OSS.
    client = oss.Client(cfg)

    # Send a request to create an inventory for a bucket.
    result = client.put_bucket_inventory(oss.PutBucketInventoryRequest(
            bucket=args.bucket, # The name of the bucket.
            inventory_id=args.inventory_id, # The ID of the inventory.
            inventory_configuration=oss.InventoryConfiguration(
                included_object_versions='All', # Specify that inventory lists include all versions of objects.
                optional_fields=oss.OptionalFields(
                    fields=[ # The optional fields, such as the size and last modified time of objects.
                        oss.InventoryOptionalFieldType.SIZE,
                        oss.InventoryOptionalFieldType.LAST_MODIFIED_DATE,
                    ],
                ),
                id=args.inventory_id, # The ID of the inventory.
                is_enabled=True, # Specify whether to enable the inventory feature for the bucket. In this example, the inventory feature is enabled.
                destination=oss.InventoryDestination(
                    oss_bucket_destination=oss.InventoryOSSBucketDestination(
                        format=oss. InventoryFormatType.CSV, # Specify that the output format of the inventory lists is CSV.
                        account_id=args.user_id, # The account ID of the user.
                        role_arn=args.arn, # The ARN of the RAM role, which has the permissions to read the objects in the source bucket and write objects to the destination bucket.
                        bucket=f'acs:oss:::{args.bucket}', # The name of the destination bucket.
                        prefix='aaa', # Specify the prefix contained in the names of the objects that you want to include in inventory lists.
                    ),
                ),
                schedule=oss.InventorySchedule(
                    frequency=oss. InventoryFrequencyType.DAILY, # Specify whether to generate inventory lists on a daily or weekly basis. In this example, inventory lists are generated on a daily basis.
                ),
                filter=oss.InventoryFilter(
                    lower_size_bound=1024, # Specify the minimum size of the object that you want to include in inventory lists. Unit: bytes.
                    upper_size_bound=1048576, # Specify the maximum size of the object that you want to include in inventory lists. Unit: bytes.
                    storage_class='ColdArchive', # # Specify the storage classes of objects that you want to include in inventory lists.
                    prefix='aaa', # Specify the prefix that is used to filter inventories.
                    last_modify_begin_time_stamp=1637883649, # Specify the beginning of the time range during which the object was last modified.
                    last_modify_end_time_stamp=1638347592, # Specify the end of the time range during which the object was last modified.
                ),
            ),
    ))

    # Display the HTTP status code of the operation and request ID to check the request status.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
    )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main() # Specify the entry points in the functions of the script. The control program flow starts here.
using Aliyun.OSS;
using Aliyun.OSS.Common;

// Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
var endpoint = "yourEndpoint";
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// Specify the name of the bucket. 
var bucketName = "examplebucket";
// Specify the account ID granted by the bucket owner. 
var accountId ="yourDestinationBucketAccountId";
// Specify the name of the RAM role that is granted the permissions to read all objects in the bucket for which you want to configure the inventory and the permissions to write data to the bucket in which you want to store the generated inventory lists. 
var roleArn ="yourDestinationBucketRoleArn";
// Specify the name of the bucket in which you want to store the generated inventory lists. 
var destBucketName ="yourDestinationBucketName";
// Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
const string region = "cn-hangzhou";

// Create a ClientConfiguration instance and modify the default parameters based on your requirements.
var conf = new ClientConfiguration();

// Use the signature algorithm V4.
conf.SignatureVersion = SignatureVersion.V4;

// Create an OSSClient instance.
var client = new OssClient(endpoint, accessKeyId, accessKeySecret, conf);
client.SetRegion(region);
try
{
    // Create an inventory for the bucket. 
    var config = new InventoryConfiguration();
    // Specify the name of the inventory. 
    config.Id = "report1";
    // Specify whether to enable the inventory for the bucket. Valid values: true and false. If this parameter is set to true, the inventory is enabled. 
    config.IsEnabled = true;
    // Specify the rule that is used to filter the objects included in inventory lists. The following code provides an example on how to filter the objects by prefix. 
    config.Filter = new InventoryFilter("filterPrefix");
    // Configure the bucket in which you want to store the generated inventory lists. 
    config.Destination = new InventoryDestination();
    config.Destination.OSSBucketDestination = new InventoryOSSBucketDestination();
    // Specify the format of the inventory lists. 
    config.Destination.OSSBucketDestination.Format = InventoryFormat.CSV;
    // Specify the ID of the account to which the destination bucket belongs. 
    config.Destination.OSSBucketDestination.AccountId = accountId;
    // Specify the Alibaba Cloud Resource Name (ARN) of the RAM role that is used to access the destination bucket. 
    config.Destination.OSSBucketDestination.RoleArn = roleArn;
    // Specify the name of the bucket in which you want to store the generated inventory lists. 
    config.Destination.OSSBucketDestination.Bucket = destBucketName;
    // Specify the prefix of the path in which you want to store the generated inventory lists. 
    config.Destination.OSSBucketDestination.Prefix = "prefix1";
    
    // Specify whether to generate the inventory lists on a daily or weekly basis. The following code provides an example on how to generate the inventory lists on a weekly basis. A value of Weekly indicates that the inventory lists are generated on a weekly basis. A value of Daily indicates that the inventory lists are generated on a daily basis. 
    config.Schedule = new InventorySchedule(InventoryFrequency.Daily);
    // Specify that the inventory lists include only the current versions of objects. If you set the InventoryIncludedObjectVersions parameter to All, all versions of objects are included in the inventory lists. This configuration takes effect only when versioning is enabled for the bucket. 
    config.IncludedObjectVersions = InventoryIncludedObjectVersions.All;
    
    // Specify the object attributes that are included in the inventory lists. 
    config.OptionalFields.Add(InventoryOptionalField.Size);
    config.OptionalFields.Add(InventoryOptionalField.LastModifiedDate);
    config.OptionalFields.Add(InventoryOptionalField.StorageClass);
    config.OptionalFields.Add(InventoryOptionalField.IsMultipartUploaded);
    config.OptionalFields.Add(InventoryOptionalField.EncryptionStatus);
    config.OptionalFields.Add(InventoryOptionalField.ETag);
    var req = new SetBucketInventoryConfigurationRequest(bucketName, config);
    client.SetBucketInventoryConfiguration(req);
    Console.WriteLine("Set bucket:{0} InventoryConfiguration succeeded", bucketName);
}
catch (OssException ex)
{
    Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
        ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* Initialize information about the account that is used to access OSS. */
            
    /* Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. */
    std::string Endpoint = "yourEndpoint";
    /* Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. */
    std::string Region = "yourRegion";
    /* Specify the name of the bucket. Example: examplebucket. */
    std::string BucketName = "examplebucket";

    /* Initialize resources, such as network resources. */
    InitializeSdk();

    ClientConfiguration conf;
    conf.signatureVersion = SignatureVersionType::V4;
    /* Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. */
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);

    InventoryConfiguration inventoryConf;
    /* Specify the name of the inventory. The name must be globally unique in the current bucket. */
    inventoryConf.setId("inventoryId");

    /* Specify whether to enable inventory for the bucket. Valid values: true and false. */
    inventoryConf.setIsEnabled(true);

    /* (Optional) Specify the prefix in the names of the objects. After you specify the prefix, information about the objects whose names contain the prefix is included in the inventory lists. */
    inventoryConf.setFilter(InventoryFilter("objectPrefix"));

    InventoryOSSBucketDestination dest;
    /* Specify the format of the exported inventory lists. */
    dest.setFormat(InventoryFormat::CSV);
    /* Specify the ID of the Alibaba Cloud account to which the bucket owner grants the permissions to perform the operation. */
    dest.setAccountId("10988548********");
    /* Specify the name of the RAM role to which the bucket owner grants permissions to perform the operation. */
    dest.setRoleArn("acs:ram::10988548********:role/inventory-test");
    /* Specify the bucket in which you want to store the generated inventory lists. */
    dest.setBucket("yourDstBucketName");
    /* Specify the prefix of the path in which you want to store the generated inventory lists. */
    dest.setPrefix("yourPrefix");
    /* (Optional) Specify the method that is used to encrypt inventory lists. Valid values: SSEOSS and SSEKMS. */
    //dest.setEncryption(InventoryEncryption(InventorySSEOSS()));
    //dest.setEncryption(InventoryEncryption(InventorySSEKMS("yourKmskeyId")));
    inventoryConf.setDestination(dest);

    /* Specify the time interval at which inventory lists are exported. Valid values: Daily and Weekly. */
    inventoryConf.setSchedule(InventoryFrequency::Daily);

    /* Specify whether to include all versions of objects or only the current versions of objects in the inventory lists. Valid values: All and Current. */
    inventoryConf.setIncludedObjectVersions(InventoryIncludedObjectVersions::All);

    /* (Optional) Specify the fields that are included in inventory lists based on your requirements. */
    InventoryOptionalFields field { 
        InventoryOptionalField::Size, InventoryOptionalField::LastModifiedDate, 
        InventoryOptionalField::ETag, InventoryOptionalField::StorageClass, 
        InventoryOptionalField::IsMultipartUploaded, InventoryOptionalField::EncryptionStatus
    };
    inventoryConf.setOptionalFields(field);

    /* Configure the inventory. */
    auto outcome = client.SetBucketInventoryConfiguration(
        SetBucketInventoryConfigurationRequest(BucketName, inventoryConf));

    if (!outcome.isSuccess()) {
        /* Handle exceptions. */
        std::cout << "Set Bucket Inventory fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* Release resources, such as network resources. */
    ShutdownSdk();
    return 0;
}
package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Define global variables.
var (
	region     string // The region in which the bucket is located.
	bucketName string // The name of the bucket.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	var (
		accountId   = "account id of the bucket" // Specify the ID of the Alibaba Cloud account to which the bucket owner grants permissions to perform the operation. Example: 109885487000****.
		inventoryId = "inventory id"             // The name of the inventory. The name must be globally unique in the bucket.
	)

	// Check whether the name of the bucket is specified.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is specified.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSS client.
	client := oss.NewClient(cfg)

	// Create a request to configure an inventory for the bucket.
	putRequest := &oss.PutBucketInventoryRequest{
		Bucket:      oss.Ptr(bucketName),  // The name of the bucket.
		InventoryId: oss.Ptr(inventoryId), // The name of the inventory specified by the user.
		InventoryConfiguration: &oss.InventoryConfiguration{
			Id:        oss.Ptr(inventoryId), // The name of the inventory specified by the user.
			IsEnabled: oss.Ptr(true),        // Enable the inventory.
			Filter: &oss.InventoryFilter{
				Prefix:                   oss.Ptr("filterPrefix"),    // Specify the rule that is used to filter the objects included in inventories.
				LastModifyBeginTimeStamp: oss.Ptr(int64(1637883649)), // The timestamp that specifies the start time of the last modification.
				LastModifyEndTimeStamp:   oss.Ptr(int64(1638347592)), // The timestamp that specifies the end time of the last modification.
				LowerSizeBound:           oss.Ptr(int64(1024)),       // The lower size limit of files (unit: bytes).
				UpperSizeBound:           oss.Ptr(int64(1048576)),    // The upper size limit of files (unit: bytes).
				StorageClass:             oss.Ptr("Standard,IA"),     // The storage class.
			},
			Destination: &oss.InventoryDestination{
				OSSBucketDestination: &oss.InventoryOSSBucketDestination{
					Format:    oss.InventoryFormatCSV,                                   // The format of the exported inventory lists.
					AccountId: oss.Ptr(accountId),                                       // Specify the ID of the account that is granted permissions by the bucket owner to perform the operation. Example: 109885487000****.
					RoleArn:   oss.Ptr("acs:ram::" + accountId + ":role/AliyunOSSRole"), // Specify the name of the RAM role that is granted permissions by the bucket owner to perform the operation. Example: acs:ram::109885487000****:role/ram-test.
					Bucket:    oss.Ptr("acs:oss:::" + bucketName),                       // Specify the name of the bucket in which you want to store the generated inventory lists.
					Prefix:    oss.Ptr("export/"),                                       // Specify the prefix of the path in which you want to store the generated inventory lists.
				},
			},
			Schedule: &oss.InventorySchedule{
				Frequency: oss.InventoryFrequencyDaily, // The frequency at which the inventory list is exported (daily).
			},
			IncludedObjectVersions: oss.Ptr("All"), // Specify whether to include all versions of objects or only the current versions of objects in the inventory list.
		},
	}

	// Execute the request.
	putResult, err := client.PutBucketInventory(context.TODO(), putRequest)
	if err != nil {
		log.Fatalf("failed to put bucket inventory %v", err)
	}

	// Display the result.
	log.Printf("put bucket inventory result:%#v\n", putResult)
}

ossutil

Create a file named inventory-configuration.xml with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration>
  <Id>report1</Id>
    <IsEnabled>true</IsEnabled>
  <Destination>
    <OSSBucketDestination>
      <Format>CSV</Format>
      <AccountId>100000000000000</AccountId>
      <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
      <Bucket>acs:oss:::destbucket</Bucket>
      <Prefix>prefix1/</Prefix>
      <Encryption>
        <SSE-KMS>
          <KeyId>keyId</KeyId>
        </SSE-KMS>
      </Encryption>
    </OSSBucketDestination>
  </Destination>
  <Schedule>
    <Frequency>Daily</Frequency>
  </Schedule>
    <IncludedObjectVersions>All</IncludedObjectVersions>
  <OptionalFields>
    <Field>Size</Field>
    <Field>LastModifiedDate</Field>
    <Field>ETag</Field>
    <Field>StorageClass</Field>
    <Field>IsMultipartUploaded</Field>
    <Field>EncryptionStatus</Field>
  </OptionalFields>
</InventoryConfiguration>

Run the following command:

ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration file://inventory-configuration.xml

Note: For more information about the put-bucket-inventory command, see put-bucket-inventory.

API

Call the PutBucketInventory operation to configure or modify an inventory rule. This method requires you to manually construct the HTTP request and calculate the signature, making it suitable for highly customized scenarios.

Inventory analysis

An inventory task runs asynchronously. All files for the inventory report are stored in a folder named after the task's start time. The key files include manifest.json and, in the data/ directory, the .csv.gz data files. To verify that the task is complete, check for the manifest.json file in the target location.

  1. Read the manifest.json file: Parse the manifest.json file to obtain the correct column order and data file information. Focus on the following two fields:

    • fileSchema: A string defining the names and exact order of the columns in the CSV file.

    • files: An array listing details about all .csv.gz data files generated for this report, including:

      • key: The path to the data file.

      • size: The size of the data file.

      • MD5checksum: The MD5 checksum of the data file.

  2. Parse CSV data files based on fileSchema

    1. Retrieve and decompress the data files: Retrieve the key (the file path) for each data file from the files array in manifest.json. Use this key to download the corresponding .csv.gz file. Decompress the file to get the data in CSV format.

    2. Parse the data in order:

      Use the column names from the fileSchema field as the CSV column headers, preserving their order. Read the decompressed CSV file line by line. Each row represents a complete record for an object, and each column corresponds to a field specified in fileSchema.

      Example CSV content: If fileSchema is "Bucket,Key,Size,StorageClass,LastModifiedDate", the decompressed CSV content is formatted as follows:

      source-bucket,"dir%2Fbody.xml","102400","Standard","2025-04-14T07-06-00Z"
      source-bucket,"dest.png","312049","Standard","2025-04-14T07-05-59Z"
      The key field is URL-encoded. Decode it as needed.

Full manifest file

Once an inventory task is configured, OSS generates inventory files at the interval specified in the inventory rule. The directory structure for the inventory files is as follows:

<dest-bucket-name>/
└── <dest-prefix>/
    └── <source-bucket-name>/
        └── <inventory-id>/
            ├── YYYY-MM-DDTHH-MMZ/  (UTC time when the scan started)
            │   ├── manifest.json   (Metadata file for the inventory task)
            │   └── manifest.checksum (MD5 checksum of the manifest.json file)
            └── data/
                └── <uuid>.csv.gz   (Multiple GZIP-compressed inventory data files)

Directory structure

Description

dest-prefix

This directory is named after the inventory report prefix you specify. If you do not specify a prefix, this directory is omitted.

source-bucket-name

This directory is named after the source bucket of the inventory report.

inventory_id

This directory is named after the inventory task's rule name.

YYYY-MM-DDTHH-MMZ

The directory name is a UTC timestamp that indicates when the bucket scan began, for example, 2025-05-17T16-00Z. This directory contains the manifest.json and manifest.checksum files.

data

This directory contains GZIP-compressed CSV inventory files that list the objects in the source bucket and the metadata for each object.

Important
  • If the source bucket contains many objects, the inventory is automatically split into multiple compressed CSV files for easier downloading and processing. The compressed CSV files are named sequentially, such as uuid.csv.gz, uuid-1.csv.gz, and uuid-2.csv.gz. You can retrieve the list of CSV files from the manifest.json file, then decompress and read them to get the complete inventory data.

  • A complete object record is always contained within a single inventory file.

Manifest file

The manifest file comprises manifest.json and manifest.checksum:

  • manifest.json: Contains metadata about the inventory.

    {
        "creationTimestamp": "1642994594",
        "destinationBucket": "dest-bucket-name",
        "fileFormat": "CSV",
        "fileSchema": "Bucket, Key, VersionId, IsLatest, IsDeleteMarker, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, EncryptionStatus, ObjectAcl, TaggingCount, ObjectType, CRC64",
        "files": [{
                "MD5checksum": "F77449179760C3B13F1E76110F07****",
                "key": "dest-prefix/source-bucket-name/inventory-id/data/a1574226-b5e5-40ee-91df-356845777c04.csv.gz",
                "size": 2046}],
        "sourceBucket": "source-bucket-name",
        "version": "2019-09-01"
    }

    The following table describes each field:

    Parameter

    Description

    creationTimestamp

    The timestamp indicating when the scan of the source bucket started.

    destinationBucket

    The destination bucket where the inventory file is stored.

    fileFormat

    The format of the inventory file.

    fileSchema

    Lists the fields in the inventory file, which are divided into fixed and optional fields. The order of the fixed fields is constant. The order of the optional fields depends on their arrangement in the inventory configuration. For example, if you use the console, the order is determined by your selection sequence. To avoid column-to-field mismatches, parse the data columns in the .csv.gz file according to the field order specified in fileSchema.

    • If you select the current version for the object version when you configure an inventory rule, the fileSchema lists the fixed fields Bucket, Key first, followed by the optional fields.

    • If you select all versions for the object version when you configure an inventory rule, the fileSchema lists the fixed fields Bucket, Key, VersionId, IsLatest, IsDeleteMarker first, followed by the optional fields.

    files

    Contains the MD5 checksum, key, and size of the inventory file.

    sourceBucket

    The source bucket being inventoried.

    version

    The inventory version.

  • manifest.checksum: The manifest.checksum file contains the MD5 hash of the manifest.json file, used to verify the integrity of the manifest.json file. For example, F77449179760C3B13F1E76110F07****.

Full inventory report

The inventory report is stored in the data/ directory and contains object information from the inventory feature. For example:

image

Parameter

Description

Bucket

The source Bucket for the inventory task.

Key

The Object's key.

The Object key is URL-encoded.

VersionId

The Object's version ID. This field appears only when the inventory is configured to include all versions.

  • If versioning is not enabled for the Bucket, this field is empty.

  • If versioning is enabled, it contains the Object's version ID.

IsLatest

Indicates if the Object is the latest version. This field appears only when the inventory is configured to include all versions.

  • If the bucket for the inventory configuration does not have versioning enabled, this field is displayed as true.

  • If versioning is enabled for the bucket specified in the inventory rule and the object is the latest version, this field is true. If the object is a previous version, this field is false.

IsDeleteMarker

Indicates if the Object version is a delete marker. This field appears only when the inventory is configured to include all versions.

  • If versioning is not enabled for the bucket specified in the inventory rule, this field defaults to false.

  • If the bucket for the inventory configuration has versioning enabled and the object is a delete marker, this field is true. If the object is not a delete marker, this field is false.

Size

The size of the Object in bytes.

StorageClass

The Object's storage class.

LastModifiedDate

The time the Object was last modified, in Coordinated Universal Time (UTC).

TransitionTime

The time a lifecycle rule transitioned the Object to the Cold Archive or Deep Cold Archive storage class.

ETag

The ETag of the Object.

An ETag is generated for each Object to identify its content.

  • For an Object created by using the PutObject API operation, the ETag is the MD5 hash of its content.

  • For Objects created by other methods, the ETag is a unique calculated value, not the MD5 hash of the content.

IsMultipartUploaded

Indicates whether the object was created by using a multipart upload. If the object was created by using a multipart upload, the value of this field is true. Otherwise, the value is false.

EncryptionStatus

Indicates whether the object is encrypted. If the object is encrypted, the value of this field is true. Otherwise, the value is false.

ObjectAcl

The object ACL. For more information, see Object ACL.

TaggingCount

The number of tags associated with the Object.

ObjectType

The type of the Object. For more information, see Object type.

CRC64

The Object's CRC64.

LastAccessDate

The last access time for the Object, in Coordinated Universal Time (UTC).

Note

This field is exported only when access tracking is enabled for the Bucket. If disabled, this field is typically null.

LastAccessTimestamp

The last access timestamp of the Object (Unix timestamp).

Note

This field is exported only when access tracking is enabled for the Bucket. If disabled, this field is typically null.

Incremental inventory

An incremental inventory typically captures and reports all object change events, including creations, metadata updates, and deletions, that occur within a 10-minute time window.

Configure an inventory rule

Console

  1. Log on to the OSS console.

  2. Navigate to the source bucket for which you want to generate an inventory. In the left navigation pane, choose Data Management > bucket inventory.

  3. On the Bucket Inventory page, click Create Inventory.

  4. In the Create Inventory panel:

    1. Configure the Basic Settings parameters.

      Parameter

      Description

      Status

      The status of the incremental inventory task. Select Start.

      Rule Name

      The name of the inventory task. The name can contain only lowercase letters, digits, and hyphens (-) and cannot start or end with a hyphen (-).

      Inventory Report Destination

      The path where the inventory report is stored. The source bucket and the destination bucket must belong to the same account and be in the same region.

      • To save the report to the exampledir1 path in the examplebucket bucket, enter exampledir1/. If the specified path does not exist in the bucket, OSS automatically creates the path. The length of the target path prefix cannot exceed 128 characters.

      • If you leave this field empty, the report is saved to the root directory.

      Important

      To prevent disruptions to the OSS-HDFS service or the risk of data corruption, do not set the inventory report directory to .dlsdata/ when you configure an inventory report rule for a bucket that has the OSS-HDFS service enabled.

      Scan Scope

      • Scan Entire Bucket: Scan all objects in the bucket.

      • Object Prefix: Scan only objects that match a specified prefix, such as exampledir1/.

    2. In the Track and Generate Incremental Metadata Updates section, enable Get Incremental Metadata Updates, and then select the Metadata Fields that you want to export.

      Parameter

      Description

      Metadata Fields

      Select the object information that you want to export.

      • Event Metadata: Serial Number, Event Type, Timestamp, User ID, Request ID, and Source IP.

      • System Metadata: Object Size, Storage Class, Last Modified Date, ETag, Multipart Upload Status, object type, object ACL, CRC64, and Encryption Status.

  5. Select I understand and agree to grant Alibaba Cloud OSS the permissions to access bucket resources, and then click OK.

Ossutil

Create a file named incremental-inventory.xml. The key difference from the full inventory configuration is the addition of the <IncrementalInventory> section.

<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration>
    <Id>Report-1</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>test</Prefix>
    </Filter>
    <Destination>
      <OSSBucketDestination>
        <Format>CSV</Format>
        <AccountId>12xxxxxx29</AccountId>
        <RoleArn>acs:ram::12xxxxxx29:role/AliyunOSSRole</RoleArn>
        <Bucket>acs:oss:::test-inc-bi-bj</Bucket>
        <Prefix>Report-1</Prefix>
      </OSSBucketDestination>
    </Destination>
    <Schedule>
      <Frequency>Weekly</Frequency>
    </Schedule>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
      <Field>Size</Field>
      <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
      <Field>StorageClass</Field>
    </OptionalFields>
    <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>CRC64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </InventoryConfiguration>

Run the following command:

ossutil api put-bucket-inventory --bucket examplebucket --inventory-id report1 --inventory-configuration file://inventory-configuration.xml
Note: For more information about the put-bucket-inventory command, see put-bucket-inventory.

API

To configure or modify an inventory rule, call the PutBucketInventory API operation. This method is ideal for highly customized scenarios but requires you to manually construct and sign the HTTP request.

Parse the inventory report

After an inventory task completes, OSS generates report files in the specified path of the destination bucket. The key files include:

  • manifest.json file

  • The .csv data files in the data/ directory

To determine if the task is complete, you can check if the manifest.json file has been generated in the destination bucket.

To parse the report, follow these steps:

  1. Read the manifest.json file: The column order of an inventory report is dynamic and depends on the fields that you select when you configure an inventory rule. You must first parse the fileSchema field in manifest.json. This field defines the names and order of the columns in the CSV file.

  2. Based on fileSchema, you can parse CSV data files

    • Use the order defined in fileSchema as the column headers of the CSV file.

    • Read a CSV file row by row: each row represents a complete record of an object (file), and each column corresponds to a field declared in fileSchema.

Incremental inventory files

After you configure an inventory task, OSS generates inventory files based on the export schedule specified in the inventory rule. The directory structure of the inventory files is as follows:

<dest-bucket-name>/
└── <dest-prefix>/
    └── <source-bucket-name>/
       └── <inventory-id>/
          └── incremental_inventory/
             └── YYYY-MM-DDTHH-MMSSZ/
                 ├── manifest.json  
                 └── data/
                     ├── uuid1_0.csv
                     └── ......

Directory component

Description

dest-prefix

This directory is named after the prefix that you specify for the inventory report. If you do not specify a prefix, this directory is omitted.

source-bucket-name

This directory is named after the source bucket for which the inventory rule is configured.

inventory_id

This directory is named after the inventory rule name.

incremental_inventory

A fixed prefix for incremental inventory reports, used to distinguish them from full inventory exports.

YYYY-MM-DDTHH-MMSSZ

This directory is named with a standard UTC timestamp that indicates when the bucket scan starts, for example, 2020-05-17T16-0000Z.

data

This directory stores inventory files in CSV format. These files list the objects and their metadata that were modified in the source bucket during the specified time window.

Manifest file

{
    "startTimestamp": "1759320000",
    "endTimestamp": "1759320600",
    "destinationBucket": "destbucket",
    "fileFormat": "CSV",
    "fileSchema": "Bucket, Key, VersionId, IsDeleteMarker, SequenceNumber, RecordType, RecordTimestamp, Requester, RequestId, SourceIp, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, ObjectType, ObjectAcl, CRC64, EncryptionStatus",
    "files": [{
            "MD5checksum": "60463A9A34019CF448A730EB2CB3****",
            "key": "dest-prefix/source-bucket-name/inventory-id/incremental_inventory/2025-09-28T07-4000Z/data/5b7c6cf0db490db906c60e87b917b148_5550506986a37a62abce56a83db6736d_0.csv",
            "size": 2046}],
    "sourceBucket": "srcbucket",
    "version": "2025-09-30"
}

The following table describes the fields.

Field

Description

startTimestamp

A timestamp that indicates the start time of the incremental inventory window.

endTimestamp

A timestamp that indicates the end time of the incremental inventory window.

destinationBucket

The destination bucket that stores the inventory files.

fileFormat

The format of the inventory files.

fileSchema

Defines the fields in the inventory file, which are either fixed or optional. The order of fixed fields is constant, but the order of optional fields depends on the sequence in which you selected them during configuration. To parse the data correctly, always use the field order defined in fileSchema.

  • If you select current version for the object version when you configure an inventory rule, the fileSchema first lists the fixed fields Bucket, Key, followed by the optional fields.

  • When you configure an inventory rule, if you select all versions for the object version, the fileSchema lists the fixed fields Bucket, Key, VersionId, IsDeleteMarker first, followed by the optional fields.

files

Contains the MD5 checksum, key, and size of each inventory file.

sourceBucket

The source bucket being inventoried.

version

The version of the manifest file.

Incremental inventory report fields

Metadata type

Field

Description

System Metadata

Bucket

The name of the source bucket.

Event Metadata

SequenceNumber

A unique sequence number for each record. For records that belong to the same object in the same bucket, sorting by SequenceNumber generally ensures a logical time order.

RecordType

The event type. Valid values: CREATE, UPDATE_METADATA, and DELETE.

  • CREATE: All upload methods under the selected prefix, such as Put, Post, Append, MultipartUpload, and Copy.

  • UPDATE_METADATA: Records all metadata updates under the selected prefix.

  • DELETE: All methods for deleting objects under the selected prefix, such as DeleteObject/DeleteMultipleObjects, creating a DeleteMarker when versioning is enabled, and lifecycle deletions. There are two types of deletion records: DeleteMarker and permanent deletion. For permanent deletion records, only the core fields Bucket, Key, SequenceNumber, RecordType, RecordTimestamp, and VersionId are retained, and the remaining columns are empty (null).

RecordTimestamp

The UTC timestamp of the event, with millisecond precision. Example: "2024-08-25 18:08:01.024".

Requester

The Alibaba Cloud account ID or Principal ID of the requester.

RequestId

The unique identifier of the request.

SourceIp

The source IP address of the requester.

System Metadata

Key

The name of the object in the bucket, URL-encoded.

VersionId

The version ID of the object. This field is included only if the inventory rule is configured to export all versions.

  • If versioning is not enabled for the source bucket, this field is empty.

  • If versioning is enabled for the source bucket, this field contains the VersionId of the object.

IsDeleteMarker

Indicates whether the object version is a delete marker. This field is included only if the inventory rule is configured to export all versions.

  • If versioning is not enabled for the bucket, this field defaults to false.

  • If versioning is enabled for the bucket, this field is true if the object is a delete marker, and false otherwise.

Size

The size of the object in bytes.

StorageClass

The storage class of the object.

LastModifiedDate

The UTC time when the object was last modified.

ETag

An ETag is created when an object is generated to identify its content.

  • For an object created by using the PutObject operation, the ETag is the MD5 hash of its content.

  • For an object created by other means, the ETag is a unique value generated based on a specific calculation rule but is not the MD5 hash of its content.

IsMultipartUploaded

Indicates whether the object was created by using a multipart upload. If so, this field is true; otherwise, it is false.

EncryptionStatus

Indicates whether the object is encrypted. If the object is encrypted, this field is true; otherwise, it is false.

ObjectAcl

The access control list (ACL) of the object. For more information, see Object ACL.

ObjectType

The type of the object. For more information, see Object Type.

CRC64

The CRC64 value of the object.

Quotas and limitations

A single bucket supports up to 1,000 inventory rules via the API or SDK, or 10 via the console.

Billing

The bucket inventory feature is free, but the following fees apply:

  • API request fees: Put request fees and Get request fees are incurred when you configure and retrieve inventory rules. PUT request fees are incurred when OSS writes an inventory report to the destination bucket. GET request fees are incurred when you download and read an inventory report.

  • Storage fees: The generated inventory reports (manifest files, csv.gz files, and csv files) consume storage space in the destination bucket and are billed at Standard storage fees.

  • Outbound traffic fees: You incur outbound traffic fees when you download and read inventory reports by using a public endpoint.

  • To avoid unnecessary costs, delete unneeded inventory rules and use lifecycle rules to automatically delete expired inventory report files.

Production use

Best practices

  • Least privilege: Always use a dedicated RAM role with the minimum required permissions. Never use AliyunOSSRole in a production environment.

  • Performance recommendations: For high-traffic source buckets, store inventory reports in a separate, dedicated destination bucket to avoid write contention that can impact the performance of your production applications.

  • Cost optimization: Bucket inventory supports daily, weekly, and monthly exports. For buckets with over 10 billion objects, we recommend using a weekly inventory. Additionally, configure a lifecycle rule on the destination bucket to automatically delete inventory reports older than a specified number of days (e.g., 30) to reduce storage costs.

    Object count

    Export recommendation

    <10 billion

    Configure daily or weekly exports as needed

    10 billion to 50 billion

    Weekly export

    ≥50 billion

    • Export in batches by matching prefixes

    • submit a ticket to increase the export limit

  • Prefix partitioning: For extremely large buckets, such as those with hundreds of billions of objects, you can create multiple inventory rules based on business prefixes. This approach generates partitioned reports that are easier to manage and process.

Risk prevention

  • Data auditing: Because Objects can be created, deleted, or overwritten while an inventory file is being exported, the final inventory list may not include all Objects. Objects with a last modified time earlier than the time specified in the createTimeStamp field of the manifest.json file will be included in the inventory file. Objects with a last modified time later than the time specified in the createTimeStamp field may not be included in the inventory file. Before you perform an operation on an Object in the inventory list, we recommend that you use the HeadObject API operation to check the Object's properties.

  • Monitoring and alerts: Monitor the storage usage of the destination bucket to prevent cost overruns caused by accumulated inventory files. Also, monitor API calls, such as PutBucketInventory, to track configuration changes.

  • Change management: Any changes to inventory rules, such as modifying a prefix or frequency, can impact downstream data analytics workflows. These changes should go through a formal review process and be managed in version control.

FAQ