This topic describes how to list all objects in a bucket, a specified number of objects in a bucket, and objects whose names contain a specified prefix in a bucket.

Methods

You can call the list or listV2 method to list up to 1,000 objects in a bucket at a time. This operation provides several parameters to customize the output. For example, you can configure parameters to list objects from a specified start position, list objects and subdirectories in a specified directory, and list objects by page. The following section describes the differences of the list and listV2 methods:

  • By default, when you use the list method to list objects, the information about the object owners is returned.
  • When you use listV2 to list objects, you must configure the fetch-owner parameter to specify whether to include the information about the object owners in the response.
    Note We recommend that you use the listV2 method to list objects in versioned buckets.

The following tables describe the parameters that you can configure when you use the list and listV2 methods to list objects.

  • Use the list method to list objects

    The following table describes the parameters that you can configure when you use the list method to list objects.

    Parameter Type Description
    prefix string The prefix that must be included in the names of the listed objects.
    delimiter string The character that is used to group objects by name.
    marker string The name of the object from which the list operation begins. If this parameter is specified, objects whose names are alphabetically after the value of the marker parameter are returned.
    max-keys number | string The maximum number of returned objects.
    encoding-type 'url' | '' Specifies that the object names in the response are URL-encoded.
  • Use the listV2 method to list objects

    The following table describes the parameters that you can configure when you use the listV2 method to list objects.

    Parameter Type Description
    prefix string The prefix that must be included in the names of the listed objects.
    continuation-token string The position from which the object list is obtained.
    delimiter string The character that is used to group the returned objects by name.
    max-keys number | string The maximum number of returned objects.
    start-after string The name of the object from which the list operation starts. If this parameter is specified, objects whose names are alphabetically after the value of the start-after parameter are returned.
    fetch-owner Boolean Specifies whether to include the information about object owners in the response.
    encoding-type 'url' | '' Specifies that the object names in the response are URL-encoded.

Simple list

The following code provides an example on how to list objects in a specified bucket. By default, up to 100 objects are listed by an operation.

  • Use the list method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
        // By default, if no parameter is specified, up to 100 objects can be returned. 
        const result = await client.list();
        console.log(result);
    }
    
    list();
  • Use the listV2 method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
        // By default, if no parameter is specified, up to 100 objects can be returned. 
        const result = await client.listV2();
        console.log(result);
    }
    
    list();

List a specified number of objects

The following code provides an example on how to list a specified number of objects in a bucket by configuring the max-keys parameter.

  • Use the list method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
        const result = await client.list({
            // Specify that the first 10 objects in alphabetical order are returned. 
          "max-keys": 10
      });
        console.log(result);
    }
    
    list();
  • Use the listV2 method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
        const result = await client.listV2({
            // Specify that the first 10 objects in alphabetical order are returned. 
          "max-keys": 10
      });
        console.log(result);
    }
    
    list();

List objects whose names contain a specified prefix

The following code provides an example on how to list objects whose names contain a specified prefix in a bucket by configuring the prefix parameter.

  • Use the list method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const result = await client.list({
        // List 10 objects. 
        "max-keys": 10,
        // List objects whose names contain the prefix foo/. 
        prefix: 'foo/'
      });
      console.log(result);
    }
    
    list();
  • Use the listV2 method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const result = await client.listV2({
        // List 10 objects. 
        "max-keys": 10,
        // List objects whose names contain the prefix foo/. 
        prefix: 'foo/'
      });
      console.log(result);
    }
    
    list();

List objects whose names are alphabetically after the specified object name

The following code provides an example on how to list objects whose names are alphabetically after the string specified by the marker or startAfter parameter.

  • Use the list method to list objects

    The name of the object from which the list operation starts is specified by the marker parameter.

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    // List the objects whose names are alphabetically after the object name test. By default, 100 objects are listed. 
    const marker = 'test'
    async function list () {
      const result = await client.list({
        marker
      });
      console.log(result);
    }
    
    list();
  • Use the listV2 method to list objects

    The name of the object from which the list operation starts is specified by the startAfter parameter.

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const result = await client.listV2({
        // List the objects and subfolders whose names are alphabetically after a/b in the a/ folder. 
        delimiter: '/',
        prefix: 'a/',
        'start-after': 'a/b'
      });
      console.log(result.objects, result.prefixes);
    }
    
    list();

List all objects in a bucket by page

The following code provides an example on how to list all objects in a specified bucket by page. You can configure the max-keys parameter to specify the maximum number of objects that can be listed on each page.

  • Use the list method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    const marker = null;
    // List up to 20 objects on each page. 
    const maxKeys = 20;
    async function list () {
      do {
        const result = await client.list({
              marker,
          'max-keys': maxKeys
          });
        marker = result.nextMarker;
            console.log(result);
      }while(marker)
    }
    
    list();
  • Use the listV2 method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const continuationToken = null;
      // List up to 20 objects on each page. 
      const maxKeys = 20;
      do {
        const result = await client.listV2({
          'continuation-token': continuationToken,
          'max-keys': maxKeys
          });
        continuationToken = result.nextContinuationToken;
            console.log(result);
      }while(continuationToken)
    }
    
    list();

List objects and object owner information

The following code provides an example on how to list objects and object owner information:

const OSS = require('ali-oss');

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Set yourbucketname to the name of your bucket. 
  bucket: 'yourbucketname'
});

// By default, the information about the object owners is not listed. To include the object owner information in the response, you must set the fetch-owner parameter to true. 
async function list () {
  const result = await client.listV2({
    'fetch-owner': true
  });
  console.log(result.objects);
}

list();

List objects and subfolders in a specified folder

The following objects are stored in the 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 list or listV2 method to list objects and subfolders in a specified folder.

  • Use the list method to list objects
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    
    // Call the listDir function and configure different prefixes to list the required objects. 
    async function listDir(dir) {
      const result = await client.list({
        prefix: dir,
        // Set delimiter to a forward slash (/). 
        delimiter: '/'
      });
    
      result.prefixes.forEach(subDir => {
        console.log('SubDir: %s', subDir);
      });
      result.objects.forEach(obj => {
        console.log('Object: %s', obj.name);
      });
    }
    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
  • Use the listV2 method
    const OSS = require('ali-oss');
    
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Set yourbucketname to the name of your bucket. 
      bucket: 'yourbucketname'
    });
    // Call the listV2Dir function and configure different prefixes to list the required objects. 
    async function listV2Dir(dir) {
      const result = await client.listV2({    
        prefix: dir,
        // Set delimiter to a forward slash (/). 
        delimiter: '/'
      });
    
      result.prefixes.forEach(subDir => {
        console.log('SubDir: %s', subDir);
      });
      result.objects.forEach(obj => {
        console.log('Object: %s', obj.name);
      });
    }
    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