列出对象

最近更新时间：2023-05-18 15:47:33
我的收藏
本页目录：

简介
本文档提供关于对象列举操作相关的 API 概览以及 SDK 示例代码。
API
操作名
操作描述
GET Bucket（List Object）
查询对象列表
查询存储桶下的部分或者全部对象
GET Bucket Object Versions
查询对象及其历史版本列表
查询存储桶下的部分或者全部对象及其历史版本信息
查询对象列表
功能说明
查询存储桶下的部分或者全部对象。
方法原型
list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)
请求示例1：列举指定存储桶中的所有对象
# -*- 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
请求示例2：列举指定前缀的对象
# -*- 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' 
)
﻿
# 列举 folder1 目录下的文件：COS中的目录是'/'结尾的前缀名
response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='folder1/' 
)
请求示例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"]
请求示例4：列出指定目录下的对象和子目录
# -*- 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	操作名	操作描述
GET Bucket（List Object）	查询对象列表	查询存储桶下的部分或者全部对象
GET Bucket Object Versions	查询对象及其历史版本列表	查询存储桶下的部分或者全部对象及其历史版本信息
参数名称	参数描述	类型	是否必填
Bucket	存储桶名称，由 BucketName-APPID 构成	String	是
Prefix	默认为空，对对象的对象键进行筛选，匹配 prefix 为前缀的对象	String	否
Delimiter	默认为空，设置分隔符，例如设置 `/` 来模拟文件夹	String	否
Marker	默认以 UTF-8 二进制顺序列出条目，标记返回对象的 list 的起点位置	String	否
MaxKeys	最多返回的对象数量，默认为最大的1000	Int	否
EncodingType	默认不编码，规定返回值的编码方式，可选值：url	String	否