Add, query, list, and delete bucket inventory configurations by using Python SDK - Object Storage Service

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

Usage notes

In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials using OSS SDK for Python 1.0.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.
Make sure that you have the permissions to create, view, list, and delete inventories for a bucket. By default, the bucket owner has the permissions to perform the preceding operations. If you do not have the permissions to perform the preceding operations, ask the bucket owner to grant you the permissions.
You can configure up to 1,000 inventories for a bucket.
You must deploy the source bucket for which you want to configure an inventory in the same region as the destination bucket in which the inventory list is stored.

Add an inventory configuration

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

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import (InventoryConfiguration,
                         InventoryFilter,
                         InventorySchedule,
                         InventoryDestination,
                         InventoryBucketDestination,
                         INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
                         INVENTORY_FREQUENCY_DAILY,
                         INVENTORY_FORMAT_CSV,
                         FIELD_SIZE,
                         FIELD_LAST_MODIFIED_DATE,
                         FIELD_STORAG_CLASS,
                         FIELD_ETAG,
                         FIELD_IS_MULTIPART_UPLOADED,
                         FIELD_ENCRYPTION_STATUS)

# 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 set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set the bucket name to examplebucket.
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Specify the ID of the account that is granted permissions by the bucket owner. Example: 1283641033516515
account_id = 'yourtBucketDestinationAccountId'
# Specify the name of the role that has permissions to read all files from the source bucket and write files to the destination bucket. Example: acs:ram::1283641033516515:role/AliyunOSSRole
role_arn = 'yourBucketDestinationRoleArn'
# Specify the name of the bucket where the inventory results are stored.
dest_bucket_name = 'yourDestinationBucketName'

# Set the name of the inventory rule.
inventory_id = "inventory1"

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

# Create a configuration for the destination bucket where the manifest file is stored.
bucket_destination = InventoryBucketDestination(
    # The AccountId of the user who owns the destination bucket.
    account_id=account_id,
    # The role ARN of the destination bucket.
    role_arn=role_arn,
    # The name of the destination bucket.
    bucket=dest_bucket_name,
    # Specify the inventory format.
    inventory_format=INVENTORY_FORMAT_CSV,
    # The prefix of the path where the inventory results are stored.
    prefix='destination-prefix',
    # To encrypt the inventory using KMS, use the following settings.
    # sse_kms_encryption=InventoryServerSideEncryptionKMS("test-kms-id"),
    # To encrypt the inventory using OSS server-side encryption, use the following settings.
    # sse_oss_encryption=InventoryServerSideEncryptionOSS()
)

# Create an inventory configuration.
inventory_configuration = InventoryConfiguration(
    # Set the ID of the inventory configuration.
    inventory_id=inventory_id,
    # Specifies whether to enable the inventory configuration. Valid values: true and false.
    is_enabled=True,
    # Set the generation schedule for the inventory. The following example sets the frequency to daily. WEEKLY specifies once a week, and DAILY specifies once a day.
    inventory_schedule=InventorySchedule(frequency=INVENTORY_FREQUENCY_DAILY),
    # Set the object versions to include in the inventory to the current versions. If you set this parameter to INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL, all object versions are included. This setting takes effect only when versioning is enabled.
    included_object_versions=INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
    # Set the prefix to filter objects for the inventory.
    # inventory_filter=InventoryFilter(prefix="obj-prefix"),
    # Set the filter conditions for the inventory. For example, the start timestamp for filtering files by last modified time is 1637883649.
    inventory_filter=InventoryFilter(
        # The prefix to match for the filter rule.
        "obj-prefix",
        # The start UNIX timestamp to filter files by last modified time. Unit: seconds.
        1637883649,
        # The end UNIX timestamp to filter files by last modified time. Unit: seconds.
        1638347592,
        # The minimum size of files to filter. Unit: bytes.
        1024,
        # The maximum size of files to filter. Unit: bytes.
        1048576,
        # The storage classes of files to filter. You can specify multiple storage classes.
        'Standard,IA'),
    # Specify the object properties to include in the inventory.
    optional_fields=optional_fields, 
    inventory_destination=InventoryDestination(bucket_destination=bucket_destination))

# Upload the inventory configuration.
result = bucket.put_bucket_inventory_configuration(inventory_configuration)
print(result.status)

View an inventory configuration

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

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

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

# 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 set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set the bucket name to examplebucket.
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Specify the name of the inventory rule.
inventory_id = "inventory1"

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

# Print the inventory configuration information.
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 inventory configurations

Note

You can query up to 100 inventories in a single request. To query more than 100 inventories, 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 inventories configured for a bucket:

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

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

# 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 set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set the bucket name to examplebucket.
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Print the inventory configuration information.
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 there are more than 100 configurations, the results are paginated. The paging information is stored in the class: <oss2.models.ListInventoryConfigurationResult>.
continuation_token = None
while 1:
    result = bucket.list_bucket_inventory_configurations(continuation_token=continuation_token)
    # Indicates whether the results of the current list operation are paginated.
    print('is truncated', result.is_truncated)
    # The token carried in the current list operation.
    print('continuaiton_token', result.continuaiton_token)
    # The token to carry for the next list operation.
    print('next_continuation_token', result.next_continuation_token)

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

    # If the current list operation is paginated, continue listing and carry the pagination token.
    if result.is_truncated:
        continuation_token = result.next_continuation_token
    else:
         break

Delete an inventory configuration

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

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

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

# 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 set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the Endpoint for the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the region information that corresponds to the Endpoint, for example, cn-hangzhou. Note that this parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set the bucket name to examplebucket.
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Specify the name of the inventory rule.
inventory_id = "inventory1"

# Delete the inventory configuration.
bucket.delete_bucket_inventory_configuration(inventory_id)

References

For the complete sample code for bucket inventory, see GitHub example.
For more information about the API operation for adding an inventory configuration for a bucket, see PutBucketInventory.
For more information about the API operation for viewing an inventory configuration for a bucket, see GetBucketInventory.
For more information about the API operation for listing inventory configurations for a bucket, see ListBucketInventory.
For more information about the API operation for deleting an inventory configuration for a bucket, see DeleteBucketInventory.