List objects (Python SDK V2)

Prerequisites

Before you begin, ensure that you have:

• A versioned OSS bucket

• The oss:ListObjectVersions permission. For details, see Attach a custom policy to a RAM user

• OSS Python SDK V2 installed (alibabacloud_oss_v2)

Usage notes

• The examples in this topic use the region ID cn-hangzhou. By default, a public endpoint is used. To access OSS from another Alibaba Cloud service in the same region, use an internal endpoint instead. See Regions and endpoints.

• Credentials are loaded from environment variables in all examples.

How it works

All examples use client.list_object_versions_paginator() to create a paginator, then call paginator.iter_page() to iterate over pages of results. Each page exposes:

• page.version: a list of object versions

Filter parameters:

Version fields (page.version items):

List all object versions

The following code lists all object versions and delete markers in a bucket, page by page.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="list object versions sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    args = parser.parse_args()

    # Load credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    # Create a paginator for listing object versions
    paginator = client.list_object_versions_paginator()

    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,
        )
    ):
        for o in page.version:
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')

if __name__ == "__main__":
    main()

List versions in a directory

Pass a prefix ending with / to scope the listing to a specific directory.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="list object versions sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    paginator = client.list_object_versions_paginator()

    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,
            prefix="exampledir/",  # List all object versions in the exampledir directory
        )
    ):
        for o in page.version:
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')

if __name__ == "__main__":
    main()

List versions by prefix

Pass a prefix string to return only versions whose object keys start with that string.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="list object versions sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    paginator = client.list_object_versions_paginator()

    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,
            prefix="test-",  # List object versions whose keys start with "test-"
        )
    ):
        for o in page.version:
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')

if __name__ == "__main__":
    main()

Control page size

Set max_keys to limit the number of versions returned per page.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="list object versions sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    args = parser.parse_args()

    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    paginator = client.list_object_versions_paginator()

    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,
            max_keys=10,  # Return up to 10 versions per page
        )
    ):
        for o in page.version:
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')

        print('-' * 30)

if __name__ == "__main__":
    main()

References

• Full sample code: list_object_versions.py