Object Storage Service:Manage bucket inventories using OSS SDK for Python 1.0

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket in the same region as your destination bucket

• The required permissions to manage inventory configurations (by default, the bucket owner has these permissions; if you are not the bucket owner, ask the owner to grant you the necessary permissions)

• Access credentials configured as environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET)

Usage notes

• This page uses the China (Hangzhou) public endpoint (https://oss-cn-hangzhou.aliyuncs.com). To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For a full list of endpoints, see Regions and endpoints.

• Access credentials in all examples are read from environment variables. For setup instructions, see Configure access credentials using OSS SDK for Python 1.0.

• All examples use oss2.ProviderAuthV4 with EnvironmentVariableCredentialsProvider. To initialize the client using a custom domain or Security Token Service (STS), see Initialization.

• A bucket supports up to 1,000 inventory configurations.

• The source bucket and the destination bucket must be in the same region.

Add an inventory configuration

The example below creates an inventory configuration that runs daily, includes current object versions, applies prefix and time-range filters, and stores results in a destination bucket.

Key parameters

# -*- 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)

# Read access credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this example.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace with the endpoint for your bucket's region.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Region ID corresponding to the endpoint above. Required for V4 signatures.
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Account ID granted permissions by the bucket owner.
# Example: 1283641033516515
account_id = 'yourtBucketDestinationAccountId'

# RAM role ARN with read access to the source bucket and write access to the destination bucket.
# Example: acs:ram::1283641033516515:role/AliyunOSSRole
role_arn = 'yourBucketDestinationRoleArn'

# Name of the bucket where inventory results are stored.
dest_bucket_name = 'yourDestinationBucketName'

# Unique ID for this inventory configuration.
inventory_id = "inventory1"

# 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]

# Configure the destination bucket where the manifest file is stored.
bucket_destination = InventoryBucketDestination(
    account_id=account_id,           # Account ID of the account granted permissions by the bucket owner
    role_arn=role_arn,               # RAM role ARN for cross-bucket access
    bucket=dest_bucket_name,         # Destination bucket name
    inventory_format=INVENTORY_FORMAT_CSV,
    prefix='destination-prefix',     # Path prefix for inventory result files
    # To enable SSE-KMS encryption, uncomment:
    # sse_kms_encryption=InventoryServerSideEncryptionKMS("test-kms-id"),
    # To enable OSS server-side encryption, uncomment:
    # sse_oss_encryption=InventoryServerSideEncryptionOSS()
)

# Build the full inventory configuration.
inventory_configuration = InventoryConfiguration(
    inventory_id=inventory_id,
    is_enabled=True,                 # Set to False to disable without deleting
    # Run the inventory once per day. Use INVENTORY_FREQUENCY_WEEKLY for weekly.
    inventory_schedule=InventorySchedule(frequency=INVENTORY_FREQUENCY_DAILY),
    # Include only current object versions. Use INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL for all versions.
    # This setting applies only when versioning is enabled on the bucket.
    included_object_versions=INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
    # Filter objects by prefix, last-modified time range (UNIX timestamps), size range (bytes), and storage class.
    inventory_filter=InventoryFilter(
        "obj-prefix",     # Prefix to match
        1637883649,       # Start of last-modified time range (seconds)
        1638347592,       # End of last-modified time range (seconds)
        1024,             # Minimum object size (bytes)
        1048576,          # Maximum object size (bytes)
        'Standard,IA'     # Storage classes to include
    ),
    optional_fields=optional_fields,
    inventory_destination=InventoryDestination(bucket_destination=bucket_destination))

result = bucket.put_bucket_inventory_configuration(inventory_configuration)
print(result.status)

Retrieve an inventory configuration

Retrieve a single inventory configuration by its ID and print its settings.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

inventory_id = "inventory1"

result = bucket.get_bucket_inventory_configuration(inventory_id=inventory_id)

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

The example below iterates through all pages and prints each configuration.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

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.')

# Paginate through all inventory configurations.
# Results are stored in oss2.models.ListInventoryConfigurationResult.
continuation_token = None
while True:
    result = bucket.list_bucket_inventory_configurations(continuation_token=continuation_token)
    print('is truncated', result.is_truncated)
    print('continuaiton_token', result.continuaiton_token)
    print('next_continuation_token', result.next_continuation_token)

    for inventory_config in result.inventory_configurations:
        print_inventory_configuration(inventory_config)

    if result.is_truncated:
        continuation_token = result.next_continuation_token
    else:
        break

Delete an inventory configuration

Delete an inventory configuration by its ID.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import os

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

inventory_id = "inventory1"

bucket.delete_bucket_inventory_configuration(inventory_id)

What's next

• GitHub example — complete sample code for bucket inventory

• PutBucketInventory — API reference for adding an inventory configuration

• GetBucketInventory — API reference for retrieving an inventory configuration

• ListBucketInventory — API reference for listing inventory configurations

• DeleteBucketInventory — API reference for deleting an inventory configuration