Help Center/ Object Storage Service/ SDK Reference/ BrowserJS/ Object Management/ Listing Objects
Updated on 2024-04-26 GMT+08:00
View PDF

Listing Objects

If you have any questions during development, post them on the Issues page of GitHub. For details about parameters and usage of each API, see the API Reference.

You can call ObsClient.listObjects to list objects in a bucket.

The following table describes the parameters involved in this API.

Parameter

Description

Prefix

Name prefix that the objects to be listed must contain

Marker

Object name to start with when listing objects in a bucket. All objects are listed in the lexicographical order.

MaxKeys

Maximum number of objects to be listed in the response body. The value ranges from 1 to 1000. If the specified value exceeds 1000, only 1,000 objects are returned.

Delimiter

Character used to group object names. If the object name contains the Delimiter parameter, the character string from the first character to the first delimiter in the object name is grouped under a single result element, CommonPrefix. (If a prefix is specified in the request, the prefix must be removed from the object name.)

For a parallel file system, if this parameter is not specified, all the content in the directory is recursively listed by default, and subdirectories are also listed. In big data scenarios, parallel file systems usually have deep directory levels and each directory has a large number of files. In such case, you are advised to configure [delimiter='/'] to list the content in the current directory, but not list subdirectories, thereby improving the listing efficiency.

Listing Objects in Simple Mode

The following sample code shows how to list objects in simple mode. A maximum of 1,000 objects can be returned.

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

obsClient.listObjects({
       Bucket : 'bucketname'
}, function (err, result) {
       if(err){              
          console.error('Error-->' + err);       
       }else{              
          console.log('Status-->' + result.CommonMsg.Status);
                 if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                        for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);
                         }
                 }            
       }
});
  • A maximum of 1,000 objects can be listed each time. If a bucket contains more than 1,000 objects, InterfaceResult.IsTruncated in the response is true, indicating not all objects were listed. In such case, you can use InterfaceResult.NextMarker to obtain the start position for the next listing.
  • If you want to obtain all objects in a specified bucket, you can use the paging mode for listing objects.

Listing Objects by Specifying the Number

Sample code:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

obsClient.listObjects({
       Bucket : 'bucketname',
       // Set the number of objects to be listed to 100.
       MaxKeys : 100
}, function (err, result) {
       if(err){              
          console.error('Error-->' + err);       
       }else{              
          console.log('Status-->' + result.CommonMsg.Status);
                 if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                        for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);
                        }
                 }            
       }
});

Listing Objects by Specifying a Prefix

Sample code:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

obsClient.listObjects({
       Bucket : 'bucketname',
       // Set the prefix to prefix and the number of objects to be listed to 100.
       MaxKeys : 100,
       Prefix : 'prefix'
}, function (err, result) {
       if(err){              
          console.error('Error-->' + err);       
       }else{              
          console.log('Status-->' + result.CommonMsg.Status);
                 if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                        for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);                                 
                         }
                 }            
       }
});

Listing Objects by Specifying the Start Position

Sample code:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

obsClient.listObjects({
       Bucket : 'bucketname',
       // Specify that 100 objects whose names follow test in lexicographical order will be listed.
       MaxKeys : 100,
       Marker : 'test'
}, function (err, result) {
       if(err){              
          console.error('Error-->' + err);       
       }else{              
          console.log('Status-->' + result.CommonMsg.Status);
                 if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                        for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);  
                         }
                 }            
       }
});

Listing All Objects in Paging Mode

Sample code:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

var listAll = function (marker) {
       obsClient.listObjects({
              Bucket : 'bucketname',
              // Set the number of parts displayed per page to 100.
              MaxKeys : 100,
              Marker : marker
       }, function (err, result) {
              if(err){              
                     console.error('Error-->' + err);       
              }else{              
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);                                  
                           }
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextMarker);
                           }
                     } 
              }
       });
};

listAll();

Listing All Objects in a Folder

There is no folder concept in OBS. All elements in buckets are objects. Folders are actually objects whose sizes are 0 and whose names end with a slash (/). When you set a folder name as the prefix, objects in this folder will be listed. Sample code is as follows:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

var listAll = function (marker) {
       obsClient.listObjects({
              Bucket : 'bucketname',
              MaxKeys : 1000,
              // Set the prefix of the folders to dir/.
              Prefix : 'dir/'
       }, function (err, result) {
              if(err){              
                     console.error('Error-->' + err);       
              }else{              
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var j in result.InterfaceResult.Contents){
                                  console.log('Contents[' + j +  ']:');
                                  console.log('Key-->' + result.InterfaceResult.Contents[j]['Key']);
                                  console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);                                  
                           }
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextMarker);
                           }
                     } 
              }
       });
};

listAll();

Listing All Objects According to Folders in a Bucket

Sample code:

// Create an instance of ObsClient.
var obsClient = new ObsClient({
    // Hard-coded or plaintext AK/SK are risky. For security purposes, encrypt your AK/SK and store them in the configuration file or environment variables. In this example, the AK/SK are stored in environment variables for identity authentication. Before running this example, configure environment variables AccessKeyID and SecretAccessKey.
    // The front-end code does not have the process environment variable, so you need to use a module bundler like webpack to define the process variable.
    // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/eu/usermanual-ca/ca_01_0003.html.
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // Replace the example endpoint with the actual one in your case.
    server: 'https://obs.eu-west-101.myhuaweicloud.eu'
});

obsClient.listObjects({
       Bucket: 'bucketname',
       // Set folder isolators to slashes (/).
       Delimiter: '/'
}, function (err, result) {
       if(!err && result.CommonMsg.Status < 300){
              console.log('Objects in the root directory:');
              for(var j in result.InterfaceResult.Contents){
                     console.log('\tKey-->' + result.InterfaceResult.Contents[j]['Key']);
                     console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);                                  
              }
              var listObjectsByPrefix = function (commonPrefixes){
                     for(var i in commonPrefixes){
                           var prefix = commonPrefixes[i]['Prefix'];
                           obsClient.listObjects({
                                  Bucket: 'bucketname',
                                  Delimiter: '/',
                                  Prefix: prefix
                           }, function (err, result) {
                                  if(!err && result.CommonMsg.Status < 300){
                                         console.log('Objects in folder:');
                                         for(var j in result.InterfaceResult.Contents){
                                                console.log('\tKey-->' + result.InterfaceResult.Contents[j]['Key']);
                                                console.log('Owner[ID]-->' + result.InterfaceResult.Contents[j]['Owner']['ID']);  
                                         }
                                         console.log('\n');
                                         if(result.InterfaceResult.CommonPrefixes && result.InterfaceResult.CommonPrefixes.length > 0){
                                                listObjectsByPrefix(result.InterfaceResult.CommonPrefixes);
                                         }
                                  }
                           });
                     }
              };
              listObjectsByPrefix(result.InterfaceResult.CommonPrefixes);
       }
});
  • The sample code does not apply to scenarios where the number of objects in a folder exceeds 1000.
  • Because objects and sub-folders in a folder are to be listed and all the objects end with a slash (/), Delimiter is always a slash (/).
  • In the returned result of each recursion, InterfaceResult.Contents includes the objects in the folder and InterfaceResult.CommonPrefixes includes the sub-folders in the folder.
Parent topic: Object Management