All Products
Search
Document Center

Object Storage Service:Bucket inventory

Last Updated:Jan 09, 2024

This topic describes how to create inventories for a bucket and how to query, list, and delete inventories configured for a bucket.

Important

If you want to use the bucket inventory feature as a RAM user, make sure that the RAM user has permissions to use the feature. For more information about permissions that are required to use the feature, see the Action element in RAM policies for OSS.

Create an inventory for a bucket

Take note of the following items when you create an inventory for a bucket:

  • You can configure up to 1,000 inventories for a bucket.

  • The source bucket for which you want to configure an inventory must be in the same region as the destination bucket in which you want to store inventory lists.

The following sample code provides an example on how to create an inventory for a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
  // 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 oss-cn-hangzhou. 
  region: 'yourregion',
  // 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. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
});

const inventory = {
  // Specify the ID of the inventory. 
  id: 'default',
  // Specify whether to enable the inventory for the bucket. Valid values: true and false. 
  isEnabled: false, 
  // (Optional) Specify the rule that is used to filter the objects in inventory lists. 
  prefix: 'ttt',
  OSSBucketDestination: {
  // Specify the format of inventory lists. 
  format: 'CSV',
  // Specify the account ID of the owner who has the destination bucket. 
  accountId: 'yourAccountId', 
  // Specify the role assumed by the account that is used to perform operations on the destination bucket. 
  rolename: 'AliyunOSSRole',
  // Specify the name of the destination bucket. 
  bucket: 'yourBucketName',
  // (Optional) Specify the prefix of the path that is used to store inventory lists. 
  prefix: 'yourPrefix ',
  // If you need to use SSE-OSS to encrypt inventory lists, refer to the following line. 
  // encryption: {'SSE-OSS': ''}
  // If you need to use SSE-KMS to encrypt inventory lists, refer to the following lines. 
           /*
            encryption: {
      'SSE-KMS': {
        keyId: 'test-kms-id';
      };
    */
  },
  // Specify whether to generate inventory lists on a daily or weekly basis. A value of Weekly indicates that inventory lists are generated on a weekly basis. A value of Daily indicates that inventory lists are generated on a daily basis. 
  frequency: 'Daily', 
  // Specify that all versions of the objects are included in inventory lists. If includedObjectVersions is set to Current, only the current versions of the objects are included in inventory lists. 
  includedObjectVersions: 'All', 
  optionalFields: {
    // (Optional) Specify object attributes that are included in inventory lists. 
    field: ["Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus"]
  },
}

async function putInventory(){
  // Specify the name of the bucket for which you want to configure the inventory. 
  const bucket = 'yourBucketName'; 
        try {
    await client.putBucketInventory(bucket, inventory);
    console.log('The inventory is created.')
  } catch(err) {
    console.log('Inventory creation failed: ', err);
  }
}

putInventory()

Query inventories configured for a bucket

The following sample code provides an example on how to query inventories for a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
  // 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 oss-cn-hangzhou. 
  region: 'yourregion',
  // 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. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
});

async function getBucketInventoryById() {
  // Specify the name of the bucket whose inventories you want to query. 
  const bucket = 'yourBucketName';
  try {
    // Query inventories configured for the bucket. 
    const result = await client.getBucketInventory(bucket, 'inventoryid');
    console.log(result.inventory);
  } catch (err) {
           console.log(err)
  }
}

getBucketInventoryById();

List multiple inventories configured for a bucket

Note

You can query up to 100 inventories by sending a request. If you want to query more than 100 inventories, send multiple requests and use the token returned for each request as a parameter for the next request.

The following sample code provides an example on how to list inventories configured for a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
  // 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 oss-cn-hangzhou. 
  region: 'yourregion',
  // 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. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
});

async function listBucketInventory() {
   // Specify the name of the bucket. 
  const bucket = 'yourBucketName';
  // List inventories configured for the bucket. 
  const result = await client.listBucketInventory(bucket);
  console.log(result.inventoryList);
  // By default, 100 inventories are listed each time. If more the 100 inventories are configured for the bucket, the inventories are listed in multiple pages. You must use the nextContinuationToken returned for the request to send the next request to list inventories in the next page. 
  const { nextContinuationToken } = result;
  const resultNext = await client.listBucketInventory(bucket, nextContinuationToken);
  console.log(result.inventoryList);
}

listBucketInventory();

Delete an inventory

The following sample code provides an example on how to delete an inventory configured for a bucket:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the name of the bucket. 
  bucket: 'yourBucketName',
  // 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 oss-cn-hangzhou. 
  region: 'yourregion',
  // 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. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
});

async function deleteBucketInventoryById() {
  // Specify the name of the bucket. 
  const bucket = 'yourBucketName';
  // Delete the inventory with the specified ID. 
  const inventory_id = 'Your InventoryId'; 
        try {
    await client.deleteBucketInventory(bucket, inventory_id);
  } catch (err) {
    console.log(err)
  }
}
deleteBucketInventoryById();

References

  • For the complete sample code that is used to manage bucket inventories, visit GitHub.

  • For more information about the API operation that you can call to create an inventory for a bucket, see PutBucketInventory.

  • For more information about the API operation that you can call to query an inventory configured for a bucket, see GetBucketInventory.

  • For more information about the API operation that you can call to list inventories configured for a bucket, see ListBucketInventory.

  • For more information about the API operation that you can call to delete the inventories configured for a bucket, see DeleteBucketInventory.