List objects - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to list all objects, a specific number of objects, and objects whose names contain a specific prefix in an Object Storage Service (OSS) bucket.

Methods

You can call the list or listV2 method to list up to 1,000 objects in a bucket at a time. You can configure parameters to list objects in different ways. For example, you can configure parameters to list objects from a specific start position, list objects and subdirectories in a specific directory, or list objects by page. The following section describes the differences between the list and listV2 methods:

When you call the list method to list objects, the information about the object owners is returned by default.
When you call the listV2 method 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 call the listV2 method to list objects in a versioned bucket.

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

Call the list method to list objects

The following table describes the parameters that you can configure when you call 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.

Call the listV2 method to list objects

The following table describes the parameters that you can configure when you call 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 token that specifies the position from which the object list is obtained.
delimiter	string	The character that is used to group 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.

List objects by using simple list

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

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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();

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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 in a bucket

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

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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();

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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 sample code provides an example on how to list objects whose names contain a specified prefix in a bucket by configuring the prefix parameter.

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

async function list () {
  const result = await client.list({
    // List 10 objects. 
    "max-keys": 10,
    // List objects whose names contain the foo/ prefix. 
    prefix: 'foo/'
  });
  console.log(result);
}

list();

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

async function list () {
  const result = await client.listV2({
    // List 10 objects. 
    "max-keys": 10,
    // List objects whose names contain the foo/ prefix. 
    prefix: 'foo/'
  });
  console.log(result);
}

list();

List objects whose names are alphabetically after a specified object name

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

Call the list method to list objects

The name of the object from which the list operation begins 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// List the objects whose names are alphabetically after the object name test. By default, up to 100 objects are listed. 
const marker = 'test'
async function list () {
  const result = await client.list({
    marker
  });
  console.log(result);
}

list();

Call the listV2 method to list objects

The name of the object from which the list operation begins 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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 sample 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.

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

let marker = null; 

// List up to 20 objects on each page. 
const maxKeys = 20;

async function list () {
  do {
    const result = await client.list({
      marker: marker, 
      'max-keys': maxKeys
    });
    marker = result.nextMarker;
    console.log(result);
  } while (marker);
}

list();

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

async function list () {
  let 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 sample 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the 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

OSS uses a flat structure to store objects. A directory is a zero-byte object whose name ends with a forward slash (/). You can upload and download this object. By default, an object whose name ends with a forward slash (/) is displayed as a directory in the OSS console. For the complete sample code that is used to create directories, visit GitHub.

If you set prefix to a directory name in the request, the objects and subdirectories whose names contain the prefix are listed.
If you specify a prefix and set delimiter to a forward slash (/) in the request, the objects and subdirectories whose names start with the specified prefix in the directory are listed. Each subdirectory is listed as a single result element in CommonPrefixes. The objects and directories in these subdirectories are not listed.

Assume that the following objects are stored in a 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 sample code provides an example on how to call the list or listV2 method to list objects and subfolders in a specified folder.

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Call the listDir function and configure different prefixes to list the required objects. 
async function listDir(dir) {
  try {
    const result = await client.list({
      prefix: dir,
      delimiter: '/'
    });
    if (result && result.prefixes) {
      result.prefixes.forEach(subDir => {
        console.log('SubDir: %s', subDir);
      });
    }
    if (result && result.objects) {
      result.objects.forEach(obj => {
        console.log('Object: %s', obj.name);
      });
    }
  } catch (e) {
    console.log(e);
  }
}

listDir('foo/');
// Expected result:
// SubDir: foo/bar/
// SubDir: foo/hello/
// Object: foo/x
// Object: foo/y

listDir('foo/bar/');
// Expected result:
// Object: foo/bar/a
// Object: foo/bar/b

listDir('foo/hello/C/');
// Expected result:
// Object: foo/hello/C/1
// Object: foo/hello/C/2
// ...
// Object: foo/hello/C/9999

Call 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',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Call the listV2Dir function and configure different prefixes to list the required objects. 
async function listV2Dir(dir) {
  try {
    const result = await client.listV2({
      prefix: dir,
      delimiter: '/'
    });
    if (result && result.prefixes) {
      result.prefixes.forEach(subDir => {
        console.log('SubDir: %s', subDir);
      });
    }
    if (result && result.objects) {
      result.objects.forEach(obj => {
        console.log('Object: %s', obj.name);
      });
    }
  } catch (e) {
    console.log(e);
  }
}

listDir('foo/');
// Expected result:
// SubDir: foo/bar/
// SubDir: foo/hello/
// Object: foo/x
// Object: foo/y

listDir('foo/bar/');
// Expected result:
// Object: foo/bar/a
// Object: foo/bar/b

listDir('foo/hello/C/');
// Expected result:
// Object: foo/hello/C/1
// Object: foo/hello/C/2
// ...
// Object: foo/hello/C/9999

References

For the complete sample code that is used to list objects, visit GitHub.
For more information about the API operations that you can call to list objects, see ListObjects (GetBucket) and ListObjectsV2 (GetBucketV2).