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

Create an inventory for a bucket

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

# -*- coding: utf-8 -*-

import oss2
from oss2.models import (InventoryConfiguration,
                        InventoryFilter, 
                        InventorySchedule, 
                        InventoryDestination, 
                        InventoryBucketDestination, 
                        InventoryServerSideEncryptionKMS,
                        InventoryServerSideEncryptionOSS,
                        INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
                        INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL,
                        INVENTORY_FREQUENCY_DAILY,
                        INVENTORY_FREQUENCY_WEEKLY,
                        INVENTORY_FORMAT_CSV,
                        FIELD_SIZE,
                        FIELD_LAST_MODIFIED_DATE,
                        FIELD_STORAG_CLASS,
                        FIELD_ETAG,
                        FIELD_IS_MULTIPART_UPLOADED,
                        FIELD_ENCRYPTION_STATUS)

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# Specify the account ID granted by the bucket owner to perform the PutBucketInventory operation. 
account_id = 'yourtBucketDestinationAccountId'
# Specify the RAM role for which you want to configure inventories. The RAM role must have permissions to read the source bucket for which you want to configure the inventory and permissions to write data to the destination bucket in which you want to store the generated inventory lists. 
role_arn = 'yourBucketDestinationRoleArn'
# Specify the name of the bucket in which you want to store the generated inventory lists. 
dest_bucket_name = 'yourDestinationBucketName'

# Specify the inventory name. 
inventory_id = "inventory1"

# Specify the object attributes to include in the inventory lists. 
optional_fields = [FIELD_SIZE, FIELD_LAST_MODIFIED_DATE, FIELD_STORAG_CLASS,
        FIELD_ETAG, FIELD_IS_MULTIPART_UPLOADED, FIELD_ENCRYPTION_STATUS]

# Create an configuration for the destination bucket. 
bucket_destination = InventoryBucketDestination(
        # Specify the ID of the Alibaba Cloud account that owns the destination bucket. 
        account_id=account_id, 
        # Specify the role ARN of the destination bucket. 
        role_arn=role_arn,
        # Specify the name of the destination bucket. 
        bucket=dest_bucket_name,
        # Specify the format of the inventory lists. 
        inventory_format=INVENTORY_FORMAT_CSV,
        # Specify the prefix of the path in which you want to store the generated inventory lists. 
        prefix='destination-prefix',
        # The following code provides an example on how to encrypt the inventory list object by using CMKs hosted in KMS. 
        # sse_kms_encryption=InventoryServerSideEncryptionKMS("test-kms-id"),
        # The following code provides an example on how to encrypt the inventory list object on the OSS server. 
        # sse_oss_encryption=InventoryServerSideEncryptionOSS()
        )

# Create an inventory configuration. 
inventory_configuration = InventoryConfiguration(
        # Specify the inventory ID. 
        inventory_id=inventory_id,
        # Specify whether the inventory is enabled. True indicates that the inventory list is generated, while false indicates that no inventory list is generated. 
        is_enabled=True, 
        # Specify whether to generate the inventory on a daily or weekly basis. The following code provides an example to generate an inventory on a daily basis.  
        inventory_schedule=InventorySchedule(frequency=INVENTORY_FREQUENCY_DAILY),
        # Set the inventory list to include only the current version. If you set this parameter to INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL, all versions are inventoried. Versioning must be enabled for this configuration to take effect. 
        included_object_versions=INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
        # Specify the prefix of object names to filter objects to include in the inventory list. 
        inventory_filter=InventoryFilter(prefix="obj-prefix"),
        # Specify the object attributes to include in the inventory list. 
        optional_fields=optional_fields,
        # Specify the destination for the inventory lists. 
        inventory_destination=InventoryDestination(bucket_destination=bucket_destination))

# Apply the inventory configuration to the bucket. 
bucket.put_bucket_inventory_configuration(inventory_configuration)

Query an inventory configured for a bucket

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

# -*- coding: utf-8 -*-

import oss2
import os

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# Specify the inventory name. 
inventory_id = "inventory1"

# Obtain the inventory configuration. 
result = bucket.get_bucket_inventory_configuration(inventory_id=inventory_id);

# Display the information about the inventory configuration. 
print('======inventory configuration======')
print('inventory_id', result.inventory_id)
print('is_enabled', result.is_enabled)
print('frequency', result.inventory_schedule.frequency)
print('included_object_versions', result.included_object_versions)
print('inventory_filter prefix', result.inventory_filter.prefix)
print('fields', result.optional_fields)
bucket_destin = result.inventory_destination.bucket_destination
print('===bucket destination===')
print('account_id', bucket_destin.account_id)
print('role_arn', bucket_destin.role_arn)
print('bucket', bucket_destin.bucket)
print('format', bucket_destin.inventory_format)
print('prefix', bucket_destin.prefix)
if bucket_destin.sse_kms_encryption is not None:
    print('server side encryption by kms, key id:', bucket_destin.sse_kms_encryption.key_id)
elif bucket_destin.sse_oss_encryption is not None:
    print('server side encryption by oss.')

List multiple inventories configured for a bucket

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

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

# -*- coding: utf-8 -*-

import oss2
import os

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# Display the information about the inventory configuration. 
def print_inventory_configuration(configuration):
    print('======inventory configuration======')
    print('inventory_id', configuration.inventory_id)
    print('is_enabled', configuration.is_enabled)
    print('frequency', configuration.inventory_schedule.frequency)
    print('included_object_versions', configuration.included_object_versions)
    print('inventory_filter prefix', configuration.inventory_filter.prefix)
    print('fields', configuration.optional_fields)
    bucket_destin = configuration.inventory_destination.bucket_destination
    print('===bucket destination===')
    print('account_id', bucket_destin.account_id)
    print('role_arn', bucket_destin.role_arn)
    print('bucket', bucket_destin.bucket)
    print('format', bucket_destin.inventory_format)
    print('prefix', bucket_destin.prefix)
    if bucket_destin.sse_kms_encryption is not None:
        print('server side encryption by kms, key id:', bucket_destin.sse_kms_encryption.key_id)
    elif bucket_destin.sse_oss_encryption is not None:
        print('server side encryption by oss.')

# List all inventory configurations. 
# If the number inventories exceeds 100, the results are returned in pages. The pagination information is stored in the <oss2.models.ListInventoryConfigurationResult> class. 
continuation_token = None
while 1:
    result = bucket.list_bucket_inventory_configurations(continuation_token=continuation_token)
    # Obtain whether the results are listed by page. 
    print('is truncated', result.is_truncated)
    # Obtain the token to carry in this list. 
    print('continuaiton_token', result.continuaiton_token)
    # Obtain the token to carry in the subsequent list. 
    print('next_continuation_token', result.next_continuation_token)

    # Display the information about the inventory configuration. 
    for inventory_config in result.inventory_configurations:
        print_inventory_configuration(inventory_config)

    # If the results are listed by page, continue the listing. The subsequent list must carry the continuation token. 
    if result.is_truncated:
        continuation_token = result.next_continuation_token
    else:
         break

Delete an inventory configured for a bucket

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

# -*- coding: utf-8 -*-

import oss2
import os

# Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# Specify the inventory name. 
inventory_id = "inventory1"

# Delete the inventory. 
bucket.delete_bucket_inventory_configuration(inventory_id)

References

  • For more information about the complete sample code for operations related to bucket inventories, visit GitHub.
  • For more information about the API operation that is called to create an inventory, see PutBucketInventory.
  • For more information about the API operation that is called to query inventories configured for a bucket, see GetBucketInventory.
  • For more information about the API operation that is called to list multiple inventories configured for a bucket, see ListBucketInventory.
  • For more information about the API operation that is called to delete inventories configured for a bucket, see DeleteBucketInventory.