tencent cloud

文档反馈

列出对象

最后更新时间:2024-01-22 11:43:35

    简介

    本文档提供关于对象列举操作相关的 API 概览以及 SDK 示例代码。
    API
    操作名
    操作描述
    查询对象列表
    查询存储桶下的部分或者全部对象
    查询对象及其历史版本列表
    查询存储桶下的部分或者全部对象及其历史版本信息

    查询对象列表

    功能说明

    查询存储桶下的部分或者全部对象。

    方法原型

    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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持