All Products
Search
Document Center

Object Storage Service:Bucket inventory

Last Updated:Jul 07, 2022

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

Notice

If you 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 section in Overview.

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.

  • Inventory lists must be stored in a destination bucket in the same region as the source bucket for which an inventory is configured.

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

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

const client = new OSS({
  // Set yourBucketName to the name of your 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',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in Object Storage Service (OSS) is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});

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 included in inventory lists. The following code provides an example on how to filter the objects by prefix. 
  prefix: 'ttt',
  OSSBucketDestination: {
  // Specify the format of inventory lists. 
  format: 'CSV',
  // Set yourAccountId to the account ID of the owner who has the destination bucket. 
  accountId: 'yourAccountId', 
  // Set AliyunOSSRole to the role assumed by the account that is used to perform operations on the destination bucket. 
  rolename: 'AliyunOSSRole',
  // Set yourBucketName to the name of the destination bucket. 
  bucket: 'yourBucketName',
  // (Optional) Set yourPrefix to the prefix of the path that is used to store inventory lists. 
  prefix: 'yourPrefix 
',
  // The following code provides an example on how to encrypt inventory lists by using SSE-OSS. 
  // encryption: {'SSE-OSS': ''}
  // The following code provides an example on how to encrypt inventory lists by using customer master keys (CMKs) managed by Key Management Service (KMS). 
           /*
            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(){
  // Set yourBucketName to the name of your bucket. 
  const bucket = 'yourBucketName'; 
        try {
    await client.putBucketInventory(bucket, inventory);
    console.log('An inventory is created.')
  } catch(err) {
    console.log('Inventory creation failed: ', err);
  }
}

putInventory()

Query the inventory configured for a bucket

The following code provides an example on how to query the inventory configured for a bucket:

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

const client = new OSS({
  // Set yourBucketName to the name of your 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',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});

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

getBucketInventoryById();

List inventories configured for a bucket

Note

You can query up to 100 inventories in a single 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 code provides an example on how to list inventories configured for a bucket:

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

const client = new OSS({
  // Set yourBucketName to the name of your 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',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});

async function listBucketInventory() {
   // Set yourBucketName to the name of your 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 configured for a bucket

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

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

const client = new OSS({
  // Set yourBucketName to the name of your 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',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});

async function deleteBucketInventoryById() {
  // Set yourBucketName to the name of your 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 of 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.