This topic describes how to list objects in a versioned bucket, including all objects, a specified number of objects, and objects whose names contain a specified prefix.

List the version information about all objects in a bucket

The following code provides an example on how to list the version information about all objects including delete markers within a specified bucket:

# -*- coding: utf-8 -*-
import oss2
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a Resource Access Management (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')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Call the list_object_versions operation to list the version information about objects in the bucket that has versioning enabled. 
# List the version information about all objects including delete markers in the bucket. 
result = bucket.list_object_versions()

# List the version information about all objects in the bucket. 
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)

    # Display the version information about the listed objects. 
    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)

    # Display the version information of the listed delete markers. 
    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)

    is_truncated = result.is_truncated

    # Check whether the version information about all the required objects in the bucket is listed. If not the version information about all the required objects is listed, continue the list operation. If the version information about all the required objects is completely listed, the list operation ends. 
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

List the version information about objects whose names contain a specified prefix

The following code provides an example on how to list the version information about objects whose names contain a specified prefix:

# -*- coding: utf-8 -*-
import oss2
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you log on as 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')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Call the list_object_versions operation to list the version information about objects in the bucket that has versioning enabled. 
# List the version information about all objects including delete markers in the bucket. 
result = bucket.list_object_versions()

# List the version information about objects whose names contain the test- prefix. 
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)

    # Display the version information about the listed objects. 
    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)

    # Display the version information about the listed delete markers. 
    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)

    is_truncated = result.is_truncated

    # Check whether the version information about all the required objects in the bucket is listed. If not the version information about all the required objects is listed, continue the list operation. If the version information about all the required objects is completely listed, the list operation ends. 
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

List the version information about a specific number of objects

The following code provides an example on how to list the version information about a specific number of objects:

# -*- coding: utf-8 -*-
import oss2
# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you log on as 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')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Set yourBucketName to the name of the bucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# Call the list_object_versions operation to list the version information about objects in the bucket that has versioning enabled. 
# List the version information about all objects including delete markers in the bucket. 
result = bucket.list_object_versions()

# List the version information about up to 200 objects. 
max_keys = 200

result = bucket.list_object_versions(max_keys=max_keys)

# Display the version information about the listed objects. 
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)

# Display the version information of the listed delete markers. 
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)

# Check whether the listed results are truncated. 
# If the number of objects in the bucket is larger than 200, the value of is_truncated is True, which indicates that the listed results are truncated. If the number of objects in the bucket is smaller than 200, the value of is_truncated is False, which indicates that the listed results are not truncated. 
print('is truncated', result.is_truncated)

List objects by directory

OSS uses a flat structure instead of a hierarchical structure to store objects. A directory is an object whose size is 0 and whose name ends with a forward slash (/). You can upload and download this object. By default, objects whose names end with a forward slash (/) are displayed as directories in the OSS console.

You can specify the delimiter and prefix parameters to list objects by directory.

  • If you set prefix to a directory name in the request, objects and subdirectories whose names contain the prefix are listed.
  • If you also set delimiter to a forward slash (/) in the request, objects and subdirectories whose names start with the specified prefix in the directory are listed. Each subdirectory is listed as a single result element in CommonPrefixes. The objects and directories in these subdirectories are not listed.

Example: A bucket named examplebucket contains the following objects: oss.jpg, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.txt. The forward slash (/) is used as the directory delimiter. The following structure shows the objects and directories in the bucket:

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

The following code provides examples on how to list objects by directory.

  • List the version information about objects within the root directory of a bucket

    The following code provides an example on how to list the version information about objects within the root directory of a bucket:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you log on as 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')
    # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Set yourBucketName to the name of the bucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')
    
    # Call the list_object_versions operation to list the version information about objects in the bucket that has versioning enabled. 
    # List the version information about all objects including delete markers in the bucket. 
    result = bucket.list_object_versions()
    
    # Specify the delimiter as a forward slash (/). 
    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)
    
        # Display the version information about the listed objects. 
        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)
    
        # Display the version information about the listed delete markers. 
        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)
    
        # Display the directories whose names end with a forward slash (/). 
        for common_prefix in result.common_prefix:
            print("common_prefix:", common_prefix)
    
        is_truncated = result.is_truncated
    
        # Check whether the version information about all the required objects in the bucket is listed. If not the version information about all the required objects is listed, continue the list operation. If the version information about all the required objects is completely listed, the list operation ends. 
        if is_truncated:
            next_key_marker = result.next_key_marker
            next_versionid_marker = result.next_versionid_marker
        else:
            break

    Returned results

    ('version_info.versionid:', 'CAEQEhiBgMCw8Y7FqBciIGIzMDE3MTEzOWRiMDRmZmFhMmRlMjljZWI0MWU4****')
    ('version_info.key:', 'oss.jpg')
    ('version_info.is_latest:', True)
    ('common_prefix:', 'fun/')
  • List objects and subdirectories in a specified directory

    The following code provides an example on how to list objects and subdirectories within a directory in a bucket:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you log on as 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')
    # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    # Set yourBucketName to the name of the bucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')
    
    # Call the list_object_versions operation to list the version information about objects in the bucket that has versioning enabled. 
    # List the version information about all objects including delete markers in the bucket. 
    result = bucket.list_object_versions()
    
    # Set delimiter to a forward slash (/) and prefix to fun/. 
    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)
    
        # Display the version information about the listed objects. 
        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)
    
        # Display the version information of the listed delete markers. 
        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)
    
        # Display the directories whose names end with a forward slash (/). 
        for common_prefix in result.common_prefix:
            print("common_prefix:", common_prefix)
    
        is_truncated = result.is_truncated
    
        # Check whether the version information about all the required objects in the bucket is listed. If not the version information about all the required objects is listed, continue the list operation. If the version information about all the required objects is completely listed, the list operation ends. 
        if is_truncated:
            next_key_marker = result.next_key_marker
            next_versionid_marker = result.next_versionid_marker
        else:
            break

    Returned results

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

References

For more information about the API operation that you can call to list objects, see GetBucketVersions(ListObjectVersions).