该接口用于列举桶中的多版本对象。每次请求返回桶的部分多版本对象(单次请求最多 1000 个),可以使用请求参数作为选择标准来返回桶中对象的子集。
要列举多版本对象,您需要拥有对桶的 tos:ListBucketVersions
权限,具体操作请参见 IAM 策略概述。
参数 | 描述 |
---|---|
prefix | 本次查询结果的前缀。 |
delimiter | 对对象名称进行分组的字符。 |
max_keys | 返回列举对象的最大数,默认值 1000。 |
key_marker | 列举多版本对象的起始位置。设定从该值之后按字母排序返回对象列表。通常为上次请求返回的 next_marker 值。 |
version_id_marker | 与 key_marker 配合使用,设定从该值之后按字典排序返回对版本对象列表。从上次列举结果中 next_version_id_marker 获取。 |
以下代码用于列举指定桶 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' prefix = "your prefix" try: # 创建 TosClientV2 对象,对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) out = client.list_object_versions(bucket_name, max_keys=10) # version 中包含多版本对象信息 for version in out.versions: print('object key', version.key) print('version id', version.version_id) print('last modified', version.last_modified) print('is latest version', version.is_latest) # 删除标记信息 for delete_marker in out.delete_markers: print('delete marker key', delete_marker.key) print('delete marker version id', delete_marker.version_id) print('delete marker last modified', delete_marker.last_modified) print('delete marker is latest version', delete_marker.is_latest) 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
前缀 example/
下的所有多版本对象和删除标记。
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' prefix = "your prefix" try: # 创建 TosClientV2 对象,对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) is_truncated = True key_marker = '' version_id_marker = '' while is_truncated: out = client.list_object_versions(bucket_name, prefix=prefix, key_marker=key_marker, version_id_marker=version_id_marker) # version 中包含多版本对象信息 for version in out.versions: print('object key', version.key) print('version id', version.version_id) print('last modified', version.last_modified) print('is latest version', version.is_latest) # 删除标记信息 for delete_marker in out.delete_markers: print('delete marker key', delete_marker.key) print('delete marker version id', delete_marker.version_id) print('delete marker last modified', delete_marker.last_modified) print('delete marker is latest version', delete_marker.is_latest) is_truncated = out.is_truncated key_marker = out.next_key_marker version_id_marker = out.next_version_id_marker 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') endpoint = "your endpoint" region = "your region" bucket_name = 'bucket-test' try: # 创建 TosClientV2 对象,对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) is_truncated = True key_marker = '' version_id_marker = '' while is_truncated: out = client.list_object_versions(bucket_name, key_marker=key_marker, version_id_marker=version_id_marker) # version 中包含多版本对象信息 for version in out.versions: print('object key', version.key) print('version id', version.version_id) print('last modified', version.last_modified) print('is latest version', version.is_latest) # 删除标记信息 for delete_marker in out.delete_markers: print('delete marker key', delete_marker.key) print('delete marker version id', delete_marker.version_id) print('delete marker last modified', delete_marker.last_modified) print('delete marker is latest version', delete_marker.is_latest) is_truncated = out.is_truncated key_marker = out.next_key_marker version_id_marker = out.next_version_id_marker 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') endpoint = "your endpoint" region = "your region" bucket_name = 'bucket-test' try: # 创建 TosClientV2 对象,对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) # 列举根目录下的文件和子文件夹 is_truncated = True next_key_marker = '' next_version_id_marker = '' while is_truncated: out = client.list_object_versions(bucket_name, delimiter="/", key_marker=next_key_marker, version_id_marker=next_version_id_marker) for prefix in out.common_prefixes: print("subDir", prefix.prefix) for version in out.versions: print('object key', version.key) print('version id', version.version_id) print('last modified', version.last_modified) print('is latest version', version.is_latest) is_truncated = out.is_truncated next_key_marker = out.next_key_marker next_version_id_marker = out.next_version_id_marker # 列举log/目录下的文件和子文件夹 is_truncated = True next_key_marker = '' next_version_id_marker = '' while is_truncated: out = client.list_object_versions(bucket_name, prefix="CLion.app/", delimiter="/", key_marker=next_key_marker, version_id_marker=next_version_id_marker) for prefix in out.common_prefixes: print("subDir", prefix.prefix) for version in out.versions: print('object key', version.key) print('version id', version.version_id) print('last modified', version.last_modified) print('is latest version', version.is_latest) is_truncated = out.is_truncated next_key_marker = out.next_key_marker next_version_id_marker = out.next_version_id_marker 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))
关于列举多版本对象的 API 文档,请参见 ListObjectsVersions。