This topic describes how to list all objects, objects whose names contain a specified prefix, and objects and subdirectories within a specified directory of a bucket.

Background information

You can call the GetBucket (ListObjects) or GetBucketV2 (ListObjectsV2) operation to list up to 1,000 objects in a bucket at a time. This operation provides several parameters to customize the output. For example, you can configure parameters to list objects from a specified start position, list objects and subdirectories in a specified directory, and list objects by page. The GetBucket (ListObjects) and GetBucketV2 (ListObjectsV2) operations are different in the following aspects:

  • By default, when you call the GetBucket (ListObjects) operation to list objects, the information about the bucket owner is included in the response.
  • When you call the GetBucketV2 (ListObjectsV2) operation to list objects, you can set the fetchOwner parameter to specify whether to include the information about the bucket owner in the response.
    Note If you want to list objects in a versioned bucket, we recommend that you call the GetBucketV2 (ListObjectsV2) operation.

The following tables describe the parameters that you can configure when you call the GetBucket (ListObjects) or GetBucketV2 (ListObjectsV2) operation to list objects.

  • Call GetBucket (ListObjects) to list objects

    The following table describes the parameters that you can configure when you call the GetBucket (ListObjects) operation to list objects.

    Parameter Description
    prefix The prefix that must be included in the names of objects to list.
    delimiter The character used to group objects by name.
    marker The position from which the list operation starts.
  • Call GetBucketV2 (ListObjectsV2) to list objects

    The following table describes the parameters that you can configure when you call the GetBucketV2 (ListObjectsV2) operation to list objects.

    Parameter Description
    prefix The prefix that must be included in the names of objects to list.
    delimiter The character used to group objects by name.
    startAfter The position from which the list operation starts.
    fetchOwner Specifies whether to include the information about the bucket owner in the response.
    • true: The response includes the owner information.
    • false: The response does not include the owner information.

Simple list

  • Call GetBucket (ListObjects) to list objects

    The following code provides an example on how to use GetBucket (ListObjects) to list 10 objects in a specified bucket:

    # -*- coding: utf-8 -*-
    import oss2
    from itertools import islice
    
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    # List 10 objects in the bucket. 
    for b in islice(oss2.ObjectIterator(bucket), 10):
        print(b.key)                    
  • Call GetBucketV2 (ListObjectsV2) to list objects

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list 10 objects in a specified bucket:

    # -*- coding: utf-8 -*-
    import oss2
    from itertools import islice
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List 10 objects in the bucket. 
    for obj in islice(oss2.ObjectIteratorV2(bucket), 10):
        print(obj.key)                    

List all objects in a bucket

  • Call GetBucket (ListObjects) to list objects

    The following code provides an example on how to call GetBucket (ListObjects) to list all objects in 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 access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects in the bucket. 
    for obj in oss2.ObjectIterator(bucket):
        print(obj.key)
  • Call GetBucketV2 (ListObjectsV2) to list objects

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list all objects in 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 access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects in the bucket. 
    for obj in oss2.ObjectIteratorV2(bucket):
        print(obj.key)
  • Call GetBucketV2 (ListObjectsV2) to list objects in a bucket and include the information about the bucket owner in the response

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list all objects in a specified bucket and how to specify the fetchOwner parameter to include the information about the bucket owner in the response:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects in the specified bucket and specify the fetchOwner parameter to include the information about the bucket owner in the response. 
    for obj in oss2.ObjectIteratorV2(bucket, fetch_owner=True):
        print(obj.key)
        print('file owner display name: ' + obj.owner.display_name)
        print('file owner id: ' + obj.owner.id)

List objects whose names contain a specified prefix

In the following examples, four objects are stored in the bucket: oss.jpg, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. A forward slash (/) is used as the directory delimiter.

  • Call GetBucket (ListObjects) to list objects

    The following code provides an example on how to call GetBucket (ListObjects) to list 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 access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects in the fun directory and its subdirectories. 
    for obj in oss2.ObjectIterator(bucket, prefix='fun/'):
        print(obj.key)
  • Call GetBucketV2 (ListObjectsV2) to list objects

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list 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 access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects in the fun directory and its subdirectories. 
    for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/'):
        print(obj.key)
  • Response
    fun/movie/001.avi
    fun/movie/007.avi
    fun/test.jpg

List all objects from a specified start position

  • Call GetBucket (ListObjects) to list objects

    You can configure the marker parameter to specify the position from which the list operation starts. All objects whose names are alphabetically after the value of marker are returned. In the following example, the bucket stores four objects: x1.txt, x2.txt, z1.txt, and z2.txt.

    The following code provides an example on how to call GetBucket (ListObjects) to list all objects from a specified start position:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects whose names are alphabetically after the value of marker. The object whose name is the same as the value of marker is not returned. 
    for obj in oss2.ObjectIterator(bucket, marker="x2.txt"):
        print(obj.key)
  • Call GetBucketV2 (ListObjectsV2) to list objects

    You can configure the start_after parameter to specify the position from which the list operation starts. All objects whose names are alphabetically after the value of start_after are returned. In the following example, the bucket stores four objects: x1.txt, x2.txt, z1.txt, and z2.txt.

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list all objects from a specified start position:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List all objects whose names are alphabetically after the value of start_after. The object whose name is the same as the value of start_after is not returned. 
    for obj in oss2.ObjectIteratorV2(bucket, start_after="x2.txt"):
        print(obj.key)

List objects and subdirectories in a specified directory

OSS uses a flat structure for objects 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 the name of a directory, objects and subdirectories whose names contain the prefix are listed.
  • If you set delimiter to a forward slash (/), only the objects and subdirectories in the directory are listed. The objects and directories in subdirectories are not listed.

The following examples show how to call GetBucket (ListObjects) and GetBucketV2 (ListObjectsV2) to list objects and subdirectories in a specified directory.

  • Call GetBucket (ListObjects) to list objects

    The following code provides an example on how to call GetBucket (ListObjects) to list objects and subdirectories in a specified directory:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List objects and subdirectories in the fun directory. Objects in the subdirectories are not listed. 
    for obj in oss2.ObjectIterator(bucket, prefix = 'fun/', delimiter = '/', start_after='fun/'):
        # Use is_prefix to determine whether obj is a directory. 
        if obj.is_prefix():  # Specify the operation to perform if obj is determined as a directory. 
            print('directory: ' + obj.key)
        else:                # Specify the operation to perform if obj is determined as an object. 
            print('file: ' + obj.key)
  • Call GetBucketV2 (ListObjectsV2) to list objects

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list objects and subdirectories in a specified directory:

    # -*- coding: utf-8 -*-
    import oss2
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    # List objects and subdirectories in the fun directory. Objects in the subdirectories are not listed. If you do not need the bucket owner information, you can leave the fetchOwner parameter unspecified. 
    for obj in oss2.ObjectIteratorV2(bucket, prefix = 'fun/', delimiter = '/', start_after='fun/', fetch_owner=True):
        # Use is_prefix to determine whether obj is a directory. 
        if obj.is_prefix():  # Specify the operation to perform if obj is determined as a directory. 
            print('directory: ' + obj.key)
        else:                # Specify the operation to perform if obj is determined as an object. 
            print('file: ' + obj.key)
            print('file owner display name: ' + obj.owner.display_name)
            print('file owner id: ' + obj.owner.id)
  • Response
    directory: fun/movie/
    file: fun/test.jpg

List the sizes of objects in a specified directory

  • Call GetBucket (ListObjects) to list the sizes of objects

    The following code provides an example on how to call GetBucket (ListObjects) to list the sizes of objects in a specified directory:

    # -*- coding: utf-8 -*-
    import oss2
    
    def CalculateFolderLength(bucket, folder):
        length = 0
        for obj in oss2.ObjectIterator(bucket, prefix=folder):
            length += obj.size
        return length
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    for obj in oss2.ObjectIterator(bucket, delimiter='/'):
        if obj.is_prefix():  # Specify the operation to perform if obj is determined as a directory. 
            length = CalculateFolderLength(bucket, obj.key)
            print('directory: ' + obj.key + '  length:' + str(length) + "Byte.")
        else: # Specify the operation to perform if obj is determined as an object. 
            print('file:' + obj.key + '  length:' + str(obj.size) + "Byte.")
  • Call GetBucketV2 (ListObjectsV2) to list the sizes of objects

    The following code provides an example on how to call GetBucketV2 (ListObjectsV2) to list the sizes of objects within a specified directory:

    # -*- coding: utf-8 -*-
    import oss2
    
    def CalculateFolderLength(bucket, folder):
        length = 0
        for obj in oss2.ObjectIteratorV2(bucket, prefix=folder):
            length += obj.size
        return length
    # The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to access OSS is a high-risk operation. We recommend that you use 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. 
    # Specify the name of the bucket. Example: examplebucket. 
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
    
    for obj in oss2.ObjectIteratorV2(bucket, delimiter='/'):
        if obj.is_prefix():  # Specify the operation to perform if obj is determined as a directory. 
            length = CalculateFolderLength(bucket, obj.key)
            print('directory: ' + obj.key + '  length:' + str(length) + "Byte.")
        else: # Specify the operation to perform if obj is determined as an object. 
            print('file:' + obj.key + '  length:' + str(obj.size) + "Byte.")