列出对象

最近更新时间:2024-08-13 17:46:41

我的收藏

简介

本文档提供关于列出对象操作相关的 API 概览以及 SDK 示例代码。

注意事项

若您要使用列出对象功能,需要先具有目标桶的读取权限:在您进行 授权策略 时,action 需要设置为 cos:GetBucket ,更多授权请参见 支持CAM的业务接口
若您要使用列出对象历史版本功能,需要先具有目标桶的读取权限:在您进行 授权策略 时,action 需要设置为 cos:GetBucketObjectVersions ,更多授权请参见 支持CAM的业务接口

相关示例

功能名称
描述
示例代码
列出对象
提供了查询存储桶下的部分或者全部对象、查询存储桶下的部分或者全部对象及其历史版本信息的能力。

使用案例:列出对象

功能说明

列出存储桶下的部分或者全部对象。

方法原型

list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)

列出指定存储桶中的第一页对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

response = client.list_objects(Bucket='examplebucket-1250000000')
if 'Contents' in response:
for content in response['Contents']:
print(content['Key'])
# 注:如果桶内对象太多,则一次列举只返回1000个对象,需要分页列举,参见示例3

请求示列出指定前缀的第一页对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

# 列举前缀为 folder 的对象
response = client.list_objects(
Bucket='examplebucket-1250000000',
Prefix='folder'
)
if 'Contents' in response:
for content in response['Contents']:
print(content['Key'])
# 注:如果桶内对象太多,则一次列举只返回1000个对象,需要分页列举,参见示例3

# 列举 folder1 目录下的文件:COS中的目录是'/'结尾的前缀名
response = client.list_objects(
Bucket='examplebucket-1250000000',
Prefix='folder1/'
)
if 'Contents' in response:
for content in response['Contents']:
print(content['Key'])
# 注:如果桶内对象太多,则一次列举只返回1000个对象,需要分页列举,参见示例3

分页列出全部对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在CosConfig中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

# 分页列举桶内对象,每个分页10个对象
marker = ""
while True:
response = client.list_objects(
Bucket='examplebucket-1250000000', Prefix='folder1/', Marker=marker, MaxKeys=10)
if 'Contents' in response:
for content in response['Contents']:
print(content['Key'])

if response['IsTruncated'] == 'false':
break

marker = response["NextMarker"]

列出指定目录下的对象和子目录

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

# 列举 folder1 目录下的文件和子目录
response = client.list_objects(
Bucket='examplebucket-1250000000', Prefix='folder1/', Delimiter='/')
# 打印文件列表
if 'Contents' in response:
for content in response['Contents']:
print(content['Key'])
# 打印子目录
if 'CommonPrefixes' in response:
for folder in response['CommonPrefixes']:
print(folder['Prefix'])

全部参数请求示例

response = client.list_objects(
Bucket='examplebucket-1250000000',
Prefix='string',
Delimiter='/',
Marker='string',
MaxKeys=100,
EncodingType='url'
)

参数说明

参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Prefix
默认为空,对对象的对象键进行筛选,匹配 prefix 为前缀的对象
String
Delimiter
默认为空,设置分隔符,例如设置 / 来模拟文件夹
String
Marker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的起点位置
String
MaxKeys
最多返回的对象数量,默认为最大的1000
Int
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String

返回结果说明

获取对象的元信息,类型为 dict:
{
'MaxKeys': '1000',
'Prefix': 'string',
'Delimiter': 'string',
'Marker': 'string',
'NextMarker': 'string',
'Name': 'examplebucket-1250000000',
'IsTruncated': 'false'|'true',
'EncodingType': 'url',
'Contents':[
{
'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"',
'StorageClass': 'STANDARD',
'Key': 'exampleobject',
'Owner': {
'DisplayName': '1250000000',
'ID': '1250000000'
},
'LastModified': '2017-08-08T09:43:35.000Z',
'Size': '23'
},
],
'CommonPrefixes':[
{
'Prefix': 'string'
},
],
}
参数名称
参数描述
类型
MaxKeys
最多返回的对象数量,默认为最大的1000
String
Prefix
默认为空,匹配 Prefix 为前缀的对象
String
Delimiter
默认为空,设置分隔符,例如设置 / 来模拟文件夹
String
Marker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的起点位置
String
NextMarker
当 IsTruncated 为 true 时,标记下一次返回对象的 list 的起点位置
String
Name
存储桶名称,由 BucketName-APPID 构成
String
IsTruncated
表示返回的对象是否被截断
String
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String
Contents
包含所有对象元数据的 list,包括 'ETag','StorageClass','Key','Owner','LastModified','Size' 等信息
List
CommonPrefixes
所有以 Prefix 开头,以 Delimiter 结尾的对象被归到同一类
List

使用案例:列出对象及其历史版本

功能说明

查询存储桶下的部分或者全部对象及其历史版本信息。

方法原型

list_objects_versions(Bucket, Prefix="", Delimiter="", KeyMarker="", VersionIdMarker="", MaxKeys=1000, EncodingType="", **kwargs)

请求示例

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在CosConfig中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

response = client.list_objects_versions(
Bucket='examplebucket-1250000000',
Prefix='string'
)

全部参数请求示例

response = client.list_objects_versions(
Bucket='examplebucket-1250000000',
Prefix='string',
Delimiter='/',
KeyMarker='string',
VersionIdMarker='string',
MaxKeys=100,
EncodingType='url'
)

参数说明

参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Prefix
默认为空,对对象的对象键进行筛选,匹配 prefix 为前缀的对象
String
Delimiter
默认为空,设置分隔符,例如设置 / 来模拟文件夹
String
KeyMarker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置
String
VersionIdMarker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置
String
MaxKeys
最多返回的对象数量,默认为最大的1000
Int
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String

返回结果说明

获取对象的元信息,类型为 dict:
{
'MaxKeys': '1000',
'Prefix': 'string',
'Delimiter': 'string',
'KeyMarker': 'string',
'VersionIdMarker': 'string',
'NextKeyMarker': 'string',
'NextVersionIdMarker': 'string',
'Name': 'examplebucket-1250000000',
'IsTruncated': 'false'|'true',
'EncodingType': 'url',
'Version':[
{
'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"',
'StorageClass': 'STANDARD',
'Key': 'exampleobject',
'VersionId': 'string',
'IsLatest': 'true'|'false',
'Owner': {
'DisplayName': '1250000000',
'ID': '1250000000'
},
'LastModified': '2017-08-08T09:43:35.000Z',
'Size': '23'
},
],
'DeleteMarker': [
{
'Key': 'exampleobject',
'VersionId': 'string',
'IsLatest': 'true'|'false',
'Owner': {
'DisplayName': '1250000000',
'ID': '1250000000'
},
'LastModified': '2017-08-08T09:43:35.000Z'
},
],
'CommonPrefixes':[
{
'Prefix': 'string'
},
],
}
参数名称
参数描述
类型
MaxKeys
最多返回的对象数量,默认为最大的1000
String
Prefix
默认为空,匹配 Prefix 为前缀的对象
String
Delimiter
默认为空,设置分隔符,例如设置 / 来模拟文件夹
String
KeyMarker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置
String
VersionIdMarker
默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置
String
NextKeyMarker
当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 Key 的起点位置
String
NextVersionIdMarker
当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 VersionId 的起点位置
String
Name
存储桶名称,由 BucketName-APPID 构成
String
IsTruncated
表示返回的对象是否被截断
String
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String
Version
包含所有多个版本对象元数据的 list,包括 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified','Size' 等信息
List
DeleteMarker
包含所有delete marker 对象元数据的 list,包括 'Key','VersionId','IsLatest','Owner','LastModified' 等信息
List
CommonPrefixes
所有以 Prefix 开头,以 Delimiter 结尾的对象被归到同一类
List

API 操作

关于列出对象的 API 接口说明,请参见 List Objects 文档。
关于列出对象历史版本的 API 接口说明,请参见 List Object versions 文档。