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

This topic describes how to list buckets that meet specified conditions in all regions within the current account.

Precautions

The sample code in this topic uses the China (Hangzhou) region ID cn-hangzhou. By default, a public endpoint is used. If you want to access OSS from other Alibaba Cloud services in the same region, you must use an internal endpoint. For more information about the mappings between OSS regions and endpoints, see OSS regions and endpoints.
The example in this topic uses environment variables to read access credentials. For more information about how to configure access credentials, 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.
When you use an SDK to list buckets, you can specify a resource group ID to filter buckets in a specific resource group.
- By default, the resource group ID parameter is not included in a request to list buckets. Therefore, the XML result 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

You can use the following code to list all buckets in all regions within the current 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

You can use the following code to list buckets that have the prefix "example" in all regions within the current 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

You can use the following code to list buckets whose names are alphabetically after "example-bucket" in all regions within the current 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

You can use the following code to list buckets in all regions within the current account and specify the maximum number of buckets to return for each 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 for listing buckets, see list_buckets.py.