List objects in a bucket by using OSS SDK for Python-Object Storage Service(OSS)-阿里云帮助中心

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.

Usage notes

The sample code in this topic uses the region ID cn-hangzhou of the China (Hangzhou) region. By default, the public endpoint is used to access resources in a bucket. If you want to access resources in the bucket by using other Alibaba Cloud services in the same region in which the bucket is located, use an internal endpoint. For more information about the OSS regions and endpoints, see Regions and endpoints.
To list objects, you must have the oss:ListObjectVersions permission. For more information, see Grant a custom policy.

Sample code

The following sample code lists the versions of all objects, including delete markers, in a bucket:

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script.
parser = argparse.ArgumentParser(description="list object versions sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the command-line arguments to obtain the specified values.
    args = parser.parse_args()

    # From the environment variables, load the authentication information required to access OSS.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Create a Paginator object that is used to list object versions by page.
    paginator = client.list_object_versions_paginator()

    # Iterate over pages.
    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,  # The bucket name.
        )
    ):
        # Iterate over object versions on the current page.
        for o in page.version:
            # Print the following information about each object version:
            # - key: the object key.
            # - size: the object size (bytes).
            # - version_id: the version ID.
            # - last_modified: the last modified time.
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')


# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Common scenarios

List all objects in a directory

The following sample code lists information about object versions in a directory specified by the prefix parameter, including the object size, last modified time, and object name:

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script.
parser = argparse.ArgumentParser(description="list object versions sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the command-line arguments to obtain the specified values.
    args = parser.parse_args()

    # From the environment variables, load the authentication information required to access OSS.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Create a Paginator object that is used to list object versions by page.
    paginator = client.list_object_versions_paginator()

    # Iterate over pages.
    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,  # The bucket name.
            prefix="exampledir/",  # List all object versions in the exampledir directory.
        )
    ):
        # Iterate over object versions on the current page.
        for o in page.version:
            # Print the following information about each object version:
            # - key: the object key.
            # - size: the object size (bytes).
            # - version_id: the version ID.
            # - last_modified: the last modified time.
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')


# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

List objects whose names contain a specific prefix

The following sample code lists information about object versions whose names contain a prefix specified by the prefix parameter, including the object size, last modified time, and object name:

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script.
parser = argparse.ArgumentParser(description="list object versions sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the command-line arguments to obtain the specified values.
    args = parser.parse_args()

    # From the environment variables, load the authentication information required to access OSS.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Create a Paginator object that is used to list object versions by page.
    paginator = client.list_object_versions_paginator()

    # Iterate over pages.
    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,  # The bucket name.
            prefix="test-",  # List object versions whose names start with the "test-" prefix.
        )
    ):
        # Iterate over object versions on the current page.
        for o in page.version:
            # Print the following information about each object version:
            # - key: the object key.
            # - size: the object size (bytes).
            # - version_id: the version ID.
            # - last_modified: the last modified time.
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')


# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

List a specific number of objects

The following sample code uses the max_keys parameter to list information about a specific number of object versions, including the object size, last modified time, and object name:

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script.
parser = argparse.ArgumentParser(description="list object versions sample")

# Specify the --region parameter to indicate the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter to indicate the name of the bucket. This parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter to indicate the endpoint of the region in which the bucket is located. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the command-line arguments to obtain the specified values.
    args = parser.parse_args()

    # From the environment variables, load the authentication information required to access OSS.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Create a Paginator object that is used to list object versions by page.
    paginator = client.list_object_versions_paginator()

    # Iterate over pages.
    for page in paginator.iter_page(oss.ListObjectVersionsRequest(
            bucket=args.bucket,  # The bucket name.
            max_keys=10,          # The maximum number of object versions that can be returned for each request.
        )
    ):
        # Iterate over object versions on the current page.
        for o in page.version:
            # Print the following information about each object version:
            # - key: the object key.
            # - size: the object size (bytes).
            # - version_id: the version ID.
            # - last_modified: the last modified time.
            print(f'Object version: {o.key}, Size: {o.size}, Version_id: {o.version_id}, Last_modified: {o.last_modified}')

        print('-' * 30)


# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

References

For the complete sample code for listing objects, see list_object_versions.py.