This topic describes how to list all objects in a bucket and objects and subdirectories within a specified directory of a bucket.

Usage notes

  • When you use packaging tools such as Webpack and Browserify, install OSS SDK for Browser.js by running the npm install ali-oss command.
  • OSS SDK for Browser.js is usually used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use a temporary access credential generated by Security Token Service (STS) to access OSS.

    For more information about how to set up STS, see Use a temporary access credential provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential. For more information, see STS SDK overview. A temporary access credential contains a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret.

List all objects in a bucket

The following code provides an example on how to use the list function to list all objects in the current bucket:

const OSS = require('ali-oss');
const client = new OSS({
   // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
   region: 'yourRegion',
   // Specify the temporary AccessKey pair obtained from STS. 
   accessKeyId: 'yourAccessKeyId',
   accessKeySecret: 'yourAccessKeySecret',
   // Specify the security token obtained from STS. 
   stsToken: 'yourSecurityToken',
   // Specify the name of the bucket. Example: examplebucket. 
   bucket: "examplebucket",
 });

async function list (dir) {
  try {
    // By default, a maximum of 1,000 objects are listed. 
    let result = await client.list();
    console.log(result);
    
    // The list operation continues from the last object that was stopped in the previous list operation. 
    if (result.isTruncated) {
      let result = await client.list({ marker : result.nextMarker });
    }

    // List the objects whose names start with the prefix my-. 
    let result = await client.list({
      prefix: 'my-'
    });
    console.log(result);

    // List all objects whose names start with the prefix my- and come after the marker my-object. 
    let result = await client.list({
      prefix: 'my-',
      marker: 'my-object'
    });
    console.log(result);
  } catch (e) {
    console.log(e);
  }
}

list();           

List objects and subfolders in a specified folder

OSS does not use a hierarchical structure for objects but instead uses a flat structure. All elements are stored as objects in buckets. However, OSS supports directories as a concept to group objects and simplify management. A directory is an object whose name ends with a forward slash (/) and whose size is 0. This object can be uploaded and downloaded. The console shows any object whose name ends with a forward slash (/) as a directory. You can use the Delimiter and Prefix parameters together to simulate directories in the following ways:

  • If Prefix is set to a directory name in the request, the objects whose names contain this prefix are listed, including all objects and subdirectories in the directory.
  • If you also set the Delimiter parameter to a forward slash (/) in the request, only objects and subdirectories in the directory are listed. The subdirectories are listed in the SubDir element, excluding recursive objects and directories in these subdirectories.

Assume that the following objects are stored in a specific bucket:

foo/x
foo/y
foo/bar/a
foo/bar/b
foo/hello/C/1
foo/hello/C/2
...
foo/hello/C/9999
            

The following code provides an example on how to use the listDir function to list objects and subdirectories in a specific directory:

const OSS = require('ali-oss');
const client = new OSS({
    // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
    region: 'yourRegion',
    // Specify the temporary AccessKey pair obtained from STS. 
    accessKeyId: 'yourAccessKeyId',
    accessKeySecret: 'yourAccessKeySecret',
    // Specify the security token obtained from STS. 
    stsToken: 'yourSecurityToken',
    // Specify the name of the bucket. Example: examplebucket. 
    bucket: "examplebucket",
   });

async function listDir (dir) {
   try {
     let result = await client.list({
       prefix: dir,
       // Set the delimiter to a forward slash (/). 
       delimiter: '/'
   });
   
   result.prefixes.forEach(function (subDir) {
      console.log('SubDir: %s', subDir);
   });
   result.objects.forEach(function (obj) {
      console.log('Object: %s', obj.name);
   });
  } catch (e) {
    console.log(e);
  }
} 

listDir()          

The following code shows the returned list results:

> listDir('foo/')
=> SubDir: foo/bar/
   SubDir: foo/hello/
   Object: foo/x
   Object: foo/y

> listDir('foo/bar/')
=> Object: foo/bar/a
   Object: foo/bar/b

> listDir('foo/hello/C/')
=> Object: foo/hello/C/1
   Object: foo/hello/C/2
   ...
   Object: foo/hello/C/9999            

References

For more information about the API operation that is called to used to list objects, see GetBucket (ListObjects).