How to list buckets by using OSS SDK for Python V2 - Object Storage Service

List buckets that meet specified conditions across all regions in your account.

Precautions

The sample code uses the China (Hangzhou) region ID cn-hangzhou and a public endpoint by default. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For more information, see OSS regions and endpoints.
The sample code reads access credentials from environment variables. For more information, see Configure access credentials.
To list buckets, you must have the oss:ListBuckets permission. For more information, see Grant custom permissions to a RAM user.
You can specify a resource group ID to filter buckets by resource group.
- By default, the resource group ID parameter is not included in a request, and the response does not contain resource group information.
- If the request includes the resource group ID parameter, OSS returns all buckets that belong to that resource group.
- If the request does not include the resource group ID parameter, OSS returns all buckets that the requester owns.

Sample code

The following code lists all buckets across all regions in your account.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This sample demonstrates how to list all buckets in OSS.
parser = argparse.ArgumentParser(description="list buckets sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This is a required parameter.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --endpoint command-line argument, which specifies the domain names that other services can use to access OSS. This is an optional parameter.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the parameters provided on the command line to obtain the user-input values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client using the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Create a paginator for the ListBuckets operation to handle many buckets.
    paginator = client.list_buckets_paginator()

    # Traverse the paginated results.
    for page in paginator.iter_page(oss.ListBucketsRequest()):
        # For each bucket on each page, print its name, location, and creation date.
        for o in page.buckets:
            print(f'Bucket: {o.name}, Location: {o.location}, Created: {o.creation_date}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, from which the program flow starts.

Scenarios

List buckets with a specified prefix

The following code lists buckets whose names start with "example" across all regions in your account.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This sample demonstrates how to list all buckets in OSS.
parser = argparse.ArgumentParser(description="list buckets sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This is a required parameter.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --endpoint command-line argument, which specifies the domain names that other services can use to access OSS. This is an optional parameter.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the parameters provided on the command line to obtain the user-input values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client using the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Create a paginator for the ListBuckets operation to handle many buckets.
    paginator = client.list_buckets_paginator()

    # Traverse the paginated results.
    for page in paginator.iter_page(oss.ListBucketsRequest(
        prefix='example', # Specify a prefix to list only buckets whose names start with "example".
        ),
    ):
        # For each bucket on each page, print its name, location, and creation date.
        for o in page.buckets:
            print(f'Bucket: {o.name}, Location: {o.location}, Created: {o.creation_date}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, from which the program flow starts.

List buckets that are after a specified marker

The following code lists buckets whose names are alphabetically after "example-bucket" across all regions in your account.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This sample demonstrates how to list all buckets in OSS.
parser = argparse.ArgumentParser(description="list buckets sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This is a required parameter.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --endpoint command-line argument, which specifies the domain names that other services can use to access OSS. This is an optional parameter.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the parameters provided on the command line to obtain the user-input values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client using the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Create a paginator for the ListBuckets operation to handle many buckets.
    paginator = client.list_buckets_paginator()

    # Traverse the paginated results.
    for page in paginator.iter_page(oss.ListBucketsRequest(
        marker="example-bucket", # List buckets whose names are alphabetically after "example-bucket".
        ),
    ):
        # For each bucket on each page, print its name, location, and creation date.
        for o in page.buckets:
            print(f'Bucket: {o.name}, Location: {o.location}, Created: {o.creation_date}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, from which the program flow starts.

List a specified number of buckets

The following code lists buckets across all regions in your account, with a specified maximum number of buckets per page.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This sample demonstrates how to list all buckets in OSS.
parser = argparse.ArgumentParser(description="list buckets sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This is a required parameter.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --endpoint command-line argument, which specifies the domain names that other services can use to access OSS. This is an optional parameter.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the parameters provided on the command line to obtain the user-input values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client using the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Create a paginator for the ListBuckets operation to handle many buckets.
    paginator = client.list_buckets_paginator()

    # Traverse the paginated results. Each page contains a specific number of buckets.
    for page in paginator.iter_page(oss.ListBucketsRequest(
        max_keys=10, # Return a maximum of 10 buckets per page.
        ),
    ):
        # For each bucket on each page, print its name, location, and creation date.
        for o in page.buckets:
            print(f'Bucket: {o.name}, Location: {o.location}, Created: {o.creation_date}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, from which the program flow starts.

List all buckets in a specified resource group

By default, the resource group ID parameter is not included in a request, and the XML result does not contain resource group information.
If you specify the resource_group_id parameter in the request, OSS returns all buckets that belong to the specified resource group.
If you do not specify the resource_group_id parameter in the request, OSS returns all buckets that the requester owns.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command-line argument parser and describe the purpose of the script: This sample demonstrates how to list all buckets in OSS.
parser = argparse.ArgumentParser(description="list buckets sample")

# Add the --region command-line argument, which specifies the region where the bucket is located. This is a required parameter.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Add the --endpoint command-line argument, which specifies the domain names that other services can use to access OSS. This is an optional parameter.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

def main():
    # Parse the parameters provided on the command line to obtain the user-input values.
    args = parser.parse_args()

    # Load the authentication information required to access OSS from environment variables for identity verification.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Create a configuration object using the default configurations of the SDK and set the authentication provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint property in the configuration object.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Initialize the OSS client using the preceding configurations to prepare for interaction with OSS.
    client = oss.Client(cfg)

    # Create a paginator for the ListBuckets operation to handle many buckets.
    paginator = client.list_buckets_paginator()

    # Traverse the paginated results. Each page contains a specific number of buckets.
    for page in paginator.iter_page(oss.ListBucketsRequest(
        max_keys=10, # Return a maximum of 10 buckets per page.
        resource_group_id="rg-aek27tc********", # List buckets in the specified resource group.
        ),
    ):
        # For each bucket on each page, print its name, location, creation date, and resource group ID.
        for o in page.buckets:
            print(f'Bucket: {o.name}, Location: {o.location}, Created: {o.creation_date}, Resource Group ID: {o.resource_group_id}')

# When this script is directly executed, call the main function to start the processing logic.
if __name__ == "__main__":
    main()  # The entry point of the script, from which the program flow starts.

References

For the complete sample code, see list_buckets.py.