Cloud Object Storage Listing Objects-SDK Documentation-Help & Documentation-Tencent Cloud

Feature Overview
This document provides an overview of APIs and SDK code samples for object listing.
API
Operation
Description
GET Bucket（List Object）
Querying the object list
Queries some or all objects in a bucket
GET Bucket Object Versions
Querying a list of objects and their version history
Queries some or all objects in a bucket as well as their version history
Querying the object list
Note
This API is used to query some or all objects in a bucket.
Method prototype
list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)
Sample 1: listing all objects in a bucket
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# Under normal circumstances, use the INFO log level. To locate issues, change it to DEBUG, and the SDK will print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket.
                           For a list of all regions supported by COS, visit https://cloud.tencent.com/document/product/436/6224
token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, see https://cloud.tencent.com/document/product/436/14048.
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
﻿
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'])
# Note: If there are too many objects in the bucket, listing will only return 1000 objects at a time. Pagination is required, see Example 3.
Sample 2: listing objects with a specified prefix
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# Under normal circumstances, use the INFO log level. To locate issues, change it to DEBUG, and the SDK will print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket.
                           For a list of all regions supported by COS, visit https://cloud.tencent.com/document/product/436/6224
token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, see https://cloud.tencent.com/document/product/436/14048.
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
# List objects with the prefix 'folder'
response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='folder' 
)
﻿
# List the files in the folder1 directory: In COS, directories are prefix names ending with '/'
response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='folder1/' 
)
Sample 3: listing objects in multiple responses
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# Under normal circumstances, use the INFO log level. To locate issues, change it to DEBUG, and the SDK will print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket.
                           For a list of all regions supported by COS, visit https://cloud.tencent.com/document/product/436/6224
token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, see https://cloud.tencent.com/document/product/436/14048.
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
# Paginate through objects in the bucket, with 10 objects per page
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"]
Sample 4: listing objects and subdirectories in a directory
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# Under normal circumstances, use the INFO log level. To locate issues, change it to DEBUG, and the SDK will print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket.
                           For a list of all regions supported by COS, visit https://cloud.tencent.com/document/product/436/6224
token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, see https://cloud.tencent.com/document/product/436/14048.
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
# List files and subdirectories under the folder1 directory
response = client.list_objects(
    Bucket='examplebucket-1250000000', Prefix='folder1/', Delimiter='/')
# Displaying the file list
if 'Contents' in response:
    for content in response['Contents']:
        print(content['Key'])
# Print subdirectories
if 'CommonPrefixes' in response:
    for folder in response['CommonPrefixes']:
        print(folder['Prefix'])
Sample request with all parameters
response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='string',
    Delimiter='/',
    Marker='string',
    MaxKeys=100,
    EncodingType='url'
)
Description
Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID
String
Required
Prefix
Filters the object keys prefixed with the value of this parameter. It is left empty by default.
String
Not required
Delimiter
A separator which is left empty by default. For example, you can specify it as / to indicate folders.
String
Not required
Marker
The object after which the returned list begins. Entries are listed in UTF-8 binary order by default.
String
Not required
MaxKeys
The maximum number of returned objects. Default value: 1000.
Int
Not required
EncodingType
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url
String
Not required
Response description
The response contains object metadata in dict format:
        {
    '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'
        },
    ],
}
Parameter name
ParameterDescription
Local Disk Types
MaxKeys
The maximum number of returned objects. Default value: 1000.
String
Prefix
Filters object keys prefixed with the value of this parameter. It is left empty by default.
String
Delimiter
A separator which is left empty by default. For example, you can specify it as / to indicate folders.
String
Marker
The object after which the returned list begins. Entries are listed in UTF-8 binary order by default.
String
NextMarker
The object after which the next returned list begins if IsTruncated is true
String
Name
Bucket name in the format of BucketName-APPID
String
IsTruncated
Indicates whether the returned objects are truncated
String
EncodingType
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url
String
Contents
List of all object metadata, including ETag, StorageClass, Key, Owner, LastModified, Size
List
CommonPrefixes
All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix
List
Querying a list of objects and their version history
Note
This API is used to query some or all objects in a bucket as well as their version history.
Method prototype
list_objects_versions(Bucket, Prefix="", Delimiter="", KeyMarker="", VersionIdMarker="", MaxKeys=1000, EncodingType="", **kwargs)
Sample Request
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# Under normal circumstances, use the INFO log level. To locate issues, change it to DEBUG, and the SDK will print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket.
                           For a list of all regions supported by COS, visit https://cloud.tencent.com/document/product/436/6224
token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, see https://cloud.tencent.com/document/product/436/14048.
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
﻿
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'
)
Sample request with all parameters
response = client.list_objects_versions(
    Bucket='examplebucket-1250000000',
    Prefix='string',
    Delimiter='/',
    KeyMarker='string',
    VersionIdMarker='string',
    MaxKeys=100,
    EncodingType='url'
)
Description
Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID
String
Required
Prefix
Filters the object keys prefixed with the value of this parameter. It is left empty by default.
String
Not required
Delimiter
A separator which is left empty by default. For example, you can specify it as / to indicate folders.
String
Not required
KeyMarker
Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default.
String
Not required
VersionIdMarker
Marks the starting version ID of the returned object list. Entries are listed in UTF-8 binary order by default.
String
Not required
MaxKeys
The maximum number of returned objects. Default value: 1000.
Int
Not required
EncodingType
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url
String
Not required
Response description
The response contains object metadata in dict format:
        {
    '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'
        },
    ],
}
Parameter name
ParameterDescription
Local Disk Types
MaxKeys
The maximum number of returned objects. Default value: 1000.
String
Prefix
Filters object keys prefixed with the value of this parameter. It is left empty by default.
String
Delimiter
A separator which is left empty by default. For example, you can specify it as / to indicate folders.
String
KeyMarker
Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default.
String
VersionIdMarker
Marks the starting version ID of the returned object list. Entries are listed in UTF-8 binary order by default.
String
NextKeyMarker
The key of the object after which the next returned list begins if IsTruncated is true
String
NextVersionIdMarker
Marks the starting version ID of the next list of returned objects if IsTruncated is set to true.
String
Name
Bucket name in the format of BucketName-APPID
String
IsTruncated
Indicates whether the returned objects are truncated
String
EncodingType
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url
String
Version
List of the metadata of all objects with multiple versions, including ETag, StorageClass, Key, VersionId, IsLatest, Owner, LastModified, and Size
List
DeleteMarker
List of the metadata of all delete markers, including Key, VersionId, IsLatest, Owner, and LastModified
List
CommonPrefixes
All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix
List
﻿
API	Operation	Description
GET Bucket（List Object）	Querying the object list	Queries some or all objects in a bucket
GET Bucket Object Versions	Querying a list of objects and their version history	Queries some or all objects in a bucket as well as their version history
Parameter name	ParameterDescription	Local Disk Types	Required
Bucket	Bucket name in the format of `BucketName-APPID`	String	Required
Prefix	Filters the object keys prefixed with the value of this parameter. It is left empty by default.	String	Not required
Delimiter	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String	Not required
Marker	The object after which the returned list begins. Entries are listed in UTF-8 binary order by default.	String	Not required
MaxKeys	The maximum number of returned objects. Default value: 1000.	Int	Not required
EncodingType	Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: `url`	String	Not required
Listing Objects

On this page:

Feature Overview

Querying the object list

Note

Method prototype

Sample 1: listing all objects in a bucket

Sample 2: listing objects with a specified prefix

Sample 3: listing objects in multiple responses

Sample 4: listing objects and subdirectories in a directory

Sample request with all parameters

Description

Response description

Querying a list of objects and their version history

Note

Method prototype

Sample Request

Sample request with all parameters

Description

Response description
