tencent cloud

Feedback

Listing Objects

Last updated: 2022-05-25 15:25:01

    Overview

    This document provides an overview of APIs and SDK code samples for listing objects.

    API Operation Description
    GET Bucket (List Objects) Querying an object list Queries some or all objects in a bucket
    GET Bucket Object Versions Querying objects and their version history Queries some or all the objects in a bucket and their version history.

    SDK API References

    For parameters and method description of all APIs in the SDK, see SDK API Reference.

    Querying an Object List

    Feature description

    This API is used to query some or all the objects in a bucket.

    Sample 1. Getting the first page of data

    Objective-C

    QCloudGetBucketRequest* request = [QCloudGetBucketRequest new];
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    request.bucket = @"examplebucket-1250000000";
    // Maximum number of objects to return at a time. Default value: 1000
    request.maxKeys = 100;
    // Prefix match, which is used to specify the address prefix of the returned files
    request.prefix = @"dir1/";
    [request setFinishBlock:^(QCloudListBucketResult * result, NSError* error) {
       // result contains the request result
       // `QCloudListBucketResult.contents` is the array of files in the bucket
       // `QCloudListBucketResult.commonPrefixes` is the array of folders in the bucket
       if (result.isTruncated) {
           // The data is truncated, and the next page of data needs to be pulled
           self->prevPageResult = result;
       }
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucket:request];
    
    Note:

    For the complete sample, go to GitHub.

    Swift

    let getBucketReq = QCloudGetBucketRequest.init();
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    getBucketReq.bucket = "examplebucket-1250000000";
    // Maximum number of objects to return at a time. Default value: 1000
    getBucketReq.maxKeys = 100;
    // Prefix match
    getBucketReq.prefix = "dir/";
    getBucketReq.setFinish { (result, error) in
       if let result = result {
           // Object list
           let contents = result.contents
           
           if (result.isTruncated) {
               // The data is truncated, and the next page of data needs to be requested
               self.prevPageResult = result;
           }
       } else {
           print(error!);
       }
    }
    QCloudCOSXMLService.defaultCOSXML().getBucket(getBucketReq);
    
    Note:

    For the complete sample, go to GitHub.

    Sample 2. Requesting the next page of data

    Objective-C

    QCloudGetBucketRequest* request = [QCloudGetBucketRequest new];
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    request.bucket = @"examplebucket-1250000000";
    // prevPageResult is the result returned on the previous page
    // Paging parameter. By default, entries are listed in UTF-8 binary order starting with the marker
    request.marker = prevPageResult.nextMarker;
    // Maximum number of objects to return at a time. Default value: 1000
    request.maxKeys = 100;
    [request setFinishBlock:^(QCloudListBucketResult * result, NSError* error) {
       // result contains the request result.
       // `QCloudListBucketResult.contents` is the array of files in the bucket
       // `QCloudListBucketResult.commonPrefixes` is the array of folders in the bucket
       if (result.isTruncated) {
           // The data is truncated, and the next page of data needs to be pulled
           self->prevPageResult = result;
       }
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucket:request];
    
    Note:

    For the complete sample, go to GitHub.

    Swift

    let getBucketReq = QCloudGetBucketRequest.init();
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    getBucketReq.bucket = "examplebucket-1250000000";
    // Paging parameter. By default, entries are listed in UTF-8 binary order starting with the marker
    if let result = self.prevPageResult {
       getBucketReq.marker = result.marker
    }
    // Maximum number of objects to return at a time. Default value: 1000
    getBucketReq.maxKeys = 100;
    // Prefix match
    getBucketReq.prefix = "dir/";
    getBucketReq.setFinish { (result, error) in
       if let result = result {
           // Object list
           let contents = result.contents
           
           if (result.isTruncated) {
               // The data is truncated, and the next page of data needs to be requested
               self.prevPageResult = result;
           }
       } else {
           print(error!);
       }
    }
    QCloudCOSXMLService.defaultCOSXML().getBucket(getBucketReq);
    
    Note:

    For the complete sample, go to GitHub.

    Sample 3. Getting an object list and subdirectories

    Objective-C

    QCloudGetBucketRequest* request = [QCloudGetBucketRequest new];
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    request.bucket = @"examplebucket-1250000000";
    // Maximum number of objects to return at a time. Default value: 1000
    request.maxKeys = 100;
    // Prefix match, which is used to specify the address prefix of the returned files
    request.prefix = @"dir1/";
    // The delimiter is a symbol. If the Prefix exists, identical paths between the Prefix and delimiter will be grouped together, 
    // which is defined as Common Prefix. Then, all common prefixes are listed. If there is no Prefix, the listing starts from the beginning of the path.
    // delimiter: path separator, which is fixed to `/`
    request.delimiter = @"/";
    // prevPageResult is the result returned on the previous page.
    // Paging parameter. By default, entries are listed in UTF-8 binary order starting with the marker
    request.marker = prevPageResult.nextMarker;
    [request setFinishBlock:^(QCloudListBucketResult * result, NSError* error) {
       // result contains the request result
       // `QCloudListBucketResult.contents` is the array of files in the bucket
       // `QCloudListBucketResult.commonPrefixes` is the array of folders in the bucket
       if (result.isTruncated) {
           // The data is truncated, and the next page of data needs to be pulled.
           self->prevPageResult = result;
       }
    }];
    [[QCloudCOSXMLService defaultCOSXML] GetBucket:request];
    
    Note:

    For the complete sample, go to GitHub.

    Swift

    let getBucketReq = QCloudGetBucketRequest.init();
    // Bucket name in the format of BucketName-APPID, which can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket
    getBucketReq.bucket = "examplebucket-1250000000";
    // Maximum number of objects to return at a time. Default value: 1000
    getBucketReq.maxKeys = 100;
    // Prefix match, which is used to specify the address prefix of the returned files
    getBucketReq.prefix = "dir/";
    // The delimiter is a symbol. If the Prefix exists, identical paths between the Prefix and delimiter will be grouped together, 
    // which is defined as Common Prefix. Then, all common prefixes are listed. If there is no Prefix, the listing starts from the beginning of the path.
    // delimiter: path separator, which is always `/`
    getBucketReq.delimiter = "/";
    // Paging parameter. By default, entries are listed in UTF-8 binary order starting with the marker
    if let result = self.prevPageResult {
       getBucketReq.marker = result.marker
    }
    getBucketReq.setFinish { (result, error) in
       if let result = result {
           // Object list
           let contents = result.contents
           
           if (result.isTruncated) {
               // The data is truncated, and the next page of data needs to be requested
               self.prevPageResult = result;
           }
       } else {
           print(error!);
       }
    }
    QCloudCOSXMLService.defaultCOSXML().getBucket(getBucketReq);
    
    Note:

    For the complete sample, go to GitHub.

    Querying an Object Version List

    Feature description

    This API is used to query some or all objects in a versioning-enabled bucket.

    Sample code: Getting the first page of data from an object version

    QCloudListObjectVersionsRequest* listObjectVersionsRequest = [[QCloudListObjectVersionsRequest alloc] init];
    // Bucket Name
    listObjectVersionsRequest.bucket = @"bucketname";
    // Number of requested data entries per page. Default value: 1000.
    listObjectVersionsRequest.maxKeys = 100;
    // List the unrequested entries from the current key
    listObjectVersionsRequest.keyMarker = prevPageResult.nextKeyMarker;
    // List the unrequested entries from an object version in the current key
    listObjectVersionsRequest.versionIdMarker = prevPageResult.nextVersionIDMarkder;
    [listObjectVersionsRequest setFinishBlock:^(QCloudListVersionsResult * _Nonnull result,
                                               NSError * _Nonnull error) {
       
       // Deleted files
       NSArray<QCloudDeleteMarker*> *deleteMarker = result.deleteMarker;
       
       // Number of object version entries
       NSArray<QCloudVersionContent*> *versionContent = result.versionContent;
       
       if (result.isTruncated) {
           // The data is truncated, and the next page of data needs to be pulled
           self->prevPageResult = result;
       }
        
    }];
    [[QCloudCOSXMLService defaultCOSXML] ListObjectVersions:listObjectVersionsRequest];
    
    Note:

    For the complete sample, go to GitHub.

    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support