Object Storage Service:List objects (OSS SDK for Python 1.0)

Prerequisites

Before you begin, ensure that you have:

• A bucket with versioning enabled

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

• Access credentials configured as environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET). For more information, see Configure access credentials using OSS SDK for Python 1.0

Usage notes

• The examples in this topic use the public endpoint for the China (Hangzhou) region. To access OSS from another Alibaba Cloud service in the same region, use an internal endpoint instead. For more information, see Regions and endpoints.

• The examples create an OSSClient instance using an OSS endpoint. To create an instance using a custom domain name or Security Token Service (STS), see Initialization.

Response fields

Each call to list_object_versions() returns a result object with the following fields:

Each item in versions and delete_marker exposes:

List all object versions

list_object_versions() returns up to 1,000 entries per request. When a bucket contains more versions than this limit, the response is truncated and is_truncated is set to True. Use next_key_marker and next_versionid_marker as pagination cursors to retrieve the remaining pages.

The following example iterates through all pages and prints every object version and delete marker in the bucket:

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

# Load 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.
# Example: https://oss-cn-hangzhou.aliyuncs.com for China (Hangzhou).
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# The region parameter is required for V4 signatures.
region = "cn-hangzhou"

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

next_key_marker = None
next_versionid_marker = None

while True:
    result = bucket.list_object_versions(
        key_marker=next_key_marker,
        versionid_marker=next_versionid_marker
    )

    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    if result.is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

List object versions with a prefix

Pass a prefix string to list_object_versions() to retrieve only the versions of objects whose names start with that prefix.

The following example lists all versions of objects whose names start with test-:

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

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

prefix = 'test-'
next_key_marker = None
next_versionid_marker = None

while True:
    result = bucket.list_object_versions(
        prefix=prefix,
        key_marker=next_key_marker,
        versionid_marker=next_versionid_marker
    )

    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    if result.is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

List a fixed number of object versions

Pass max_keys to cap the number of entries returned in a single call. Check is_truncated afterward to determine whether more results exist.

The following example retrieves up to 200 versions in a single request:

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

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

result = bucket.list_object_versions(max_keys=200)

for version_info in result.versions:
    print('version_info.versionid:', version_info.versionid)
    print('version_info.key:', version_info.key)
    print('version_info.is_latest:', version_info.is_latest)

for del_maker_Info in result.delete_marker:
    print('del_maker.key:', del_maker_Info.key)
    print('del_maker.versionid:', del_maker_Info.versionid)
    print('del_maker.is_latest:', del_maker_Info.is_latest)

# True if the bucket contains more than 200 versions; False otherwise.
print('is truncated:', result.is_truncated)

List object versions by folder

OSS has no native folder structure — all elements are stored as objects. A folder is a zero-byte object whose name ends with /. The OSS console displays such objects as folders.

Use the delimiter and prefix parameters together to simulate folder navigation:

When delimiter is /, subfolders appear in result.common_prefix rather than in result.versions, so their contents are not listed in the same response.

Assume examplebucket contains the following objects:

examplebucket
 └── oss.jpg
 └── fun/
      └── test.jpg
      └── movie/
           └── 001.avi
           └── 007.txt

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

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

delimiter = "/"
next_key_marker = None
next_versionid_marker = None

while True:
    result = bucket.list_object_versions(
        delimiter=delimiter,
        key_marker=next_key_marker,
        versionid_marker=next_versionid_marker
    )

    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    # Subfolder names (ending with /) appear here, not in result.versions.
    for common_prefix in result.common_prefix:
        print("common_prefix:", common_prefix)

    if result.is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

('version_info.versionid:', 'CAEQEhiBgMCw8Y7FqBciIGIzMDE3MTEzOWRiMDRmZmFhMmRlMjljZWI0MWU4****')
('version_info.key:', 'oss.jpg')
('version_info.is_latest:', True)
('common_prefix:', 'fun/')

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

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

prefix = "fun/"
delimiter = "/"
next_key_marker = None
next_versionid_marker = None

while True:
    result = bucket.list_object_versions(
        prefix=prefix,
        delimiter=delimiter,
        key_marker=next_key_marker,
        versionid_marker=next_versionid_marker
    )

    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    # Subfolders within fun/ appear here (e.g., fun/movie/).
    for common_prefix in result.common_prefix:
        print("common_prefix:", common_prefix)

    if result.is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

('version_info.versionid:', 'CAEQFRiBgMCh9JDkrxciIGE3OTNkYzFhYTc2YzQzOTQ4Y2MzYjg2YjQ4ODg*****')
('version_info.key:', 'fun/test.jpg')
('version_info.is_latest:', True)
('commonPrefix:', 'fun/movie/')

What's next

For the underlying API, see ListObjectVersions (GetBucketVersions).