列举对象 V2（Python SDK）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

列举对象 V2（Python SDK）

最近更新时间：2024.09.27 14:37:36首次发布时间：2023.01.19 18:21:16

本文介绍如何通过 ListObjectsType2 列举指定桶下的所有对象、指定前缀文件、指定目录下的文件和子目录。

注意事项

ListObjects 接口已经修订为 ListObjectsType2，强烈建议开发者使用 ListObjectsType2。为保障向后兼容性，TOS 继续支持 ListObjects 接口。
使用列举对象 V2，您必须具有 tos:ListBucket 权限，具体操作，请参见 IAM 策略概述。

参数说明

ListObjectsType2 支持的参数如下。

参数	描述
prefix	本次查询结果的前缀。
delimiter	对对象名称进行分组的字符。
start_after	此次列举对象的起点。
continuation_token	指定列举操作需要从此 token 开始。可从上次列举结果中的 next_continuation_token 中获取。
max_keys	返回列举对象的最大数，默认值 1000。取值：大于 0 小于等于 1000。

示例代码

简单列举

以下代码用于列举桶 bucket-test 中最多 10 个对象。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)

    # 列举桶中的10个对象示例代码如下：
    result = client.list_objects_type2(bucket_name, max_keys=10)
    for item in result.contents:
        print(item.key)

except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

分页列举

以下代码用于分页列举桶 bucket-test 中的对象。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
try:
    client = tos.TosClientV2(ak, sk, endpoint, region)

    # 分页列举桶中前1000个对象
    result = client.list_objects_type2(bucket_name)
    for item in result.contents:
        print(item.key)
    # 若未例举完分页列举后续1000个对象
    if result.is_truncated:
        result = client.list_objects_type2(bucket_name, continuation_token=result.next_continuation_token)
        for item in result.contents:
            print(item.key)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

列举指定前缀的所有对象

以下代码用于列举桶 bucket-test 中指定前缀的的所有对象。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
prefix = "your prefix"
try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)

    # 列举指定桶下特定前缀所有对象
    truncated = True
    continuation_token = ''

    while truncated:
        result = client.list_objects_type2(bucket_name, prefix=prefix, continuation_token=continuation_token)
        for item in result.contents:
            print(item.key)
        truncated = result.is_truncated
        continuation_token = result.next_continuation_token
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

列举桶内所有对象

以下代码用于列举桶 bucket-test 中所有对象。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 列举指定桶下所有对象
    truncated = True
    continuation_token = ''
    while truncated:
        result = client.list_objects_type2(bucket_name, continuation_token=continuation_token)
        for item in result.contents:
            print(item.key)
        truncated = result.is_truncated
        continuation_token = result.next_continuation_token
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

TOS 只有对象的概念, 可通过创建一个大小为 0 并且以斜线 / 结尾的对象, 模拟目录的功能。
通过 delimiter 和 prefix 两个参数可以模拟目录的功能:

首先设置 delimiter 为 / 同时设置 prefix 为空, 可返回根目录下的对象和子目录信息。
在设置 delimiter 为 / 同时设置 prefix 为子目录, 可返回子目录的对象和次级目录。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。
endpoint = "your endpoint"
region = "your region"
bucket_name = "bucket-test"
try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 向Bucket中添加fun1、fun2、fun3 的子目录与名为test的文件
    client.put_object(bucket_name, "fun1/")
    client.put_object(bucket_name, "fun1/test/")
    client.put_object(bucket_name, "fun1/obj.txt")
    client.put_object(bucket_name, "fun2/")
    client.put_object(bucket_name, "fun3/")
    client.put_object(bucket_name, "test")

    # 1. 列举根目录下文件和子目录
    is_truncated = True
    next_continuation_token = ''
    while is_truncated:
        out = client.list_objects_type2(bucket_name, delimiter="/", continuation_token=next_continuation_token)
        is_truncated = out.is_truncated
        next_continuation_token = out.next_continuation_token
        # common_prefixes中返回了根目录下的子目录
        for prefix in out.common_prefixes:
            print('subDir', prefix.prefix)

        # contents中返回了根目录下的对象
        for content in out.contents:
            print('file', content.key)

    # 2. 列举 fun1/ 目录下文件和子目录
    is_truncated = True
    next_continuation_token = ''
    while is_truncated:
        out = client.list_objects_type2(bucket_name, delimiter="/", prefix="fun1/", continuation_token=next_continuation_token)
        is_truncated = out.is_truncated
        next_continuation_token = out.next_continuation_token
        # common_prefixes中返回了fun1/目录下的子目录
        for prefix in out.common_prefixes:
            print('subDir', prefix.prefix)

        # contents中返回了fun1/目录下的对象
        for content in out.contents:
            print('file', content.key)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))