All Products
Search
Document Center

Object Storage Service:List objects

Last Updated:Oct 30, 2023

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

List the versions of all objects in a bucket

The following sample code provides an example on how to list the versions of all objects including delete markers in a specified bucket:

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 the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// List the versions of all objects in the bucket, including delete markers. 
async function getObjectVersions() {
  let nextKeyMarker = null;
  let nextVersionMarker = null;
  let versionListing = null;
  do {
    versionListing = await client.getBucketVersions({
      keyMarker: nextKeyMarker,
      versionIdMarker: nextVersionMarker,
    });

    versionListing.objects.forEach((o) => {
      console.log(`${o.name}, ${o.versionId}`);
    });
    versionListing.deleteMarker.forEach((o) => {
      console.log(`${o.name}, ${o.versionId}`);
    });

    nextKeyMarker = versionListing.NextKeyMarker;
    nextVersionMarker = versionListing.NextVersionIdMarker;
  } while (versionListing.isTruncated);
}

getObjectVersions();

List the versions of objects whose names contain a specified prefix

The following sample code provides an example on how to list the versions of objects whose names contain a specified prefix:

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 the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// List all versions of objects whose names contain the "test-" prefix. 
async function getObjectVersionsByPrefix() {
  let nextKeyMarker = null;
  let nextVersionMarker = null;
  let versionListing = null;
  const prefix = 'test-'
  do {
    versionListing = await client.getBucketVersions({
      keyMarker: nextKeyMarker,
      versionIdMarker: nextVersionMarker,
      prefix
    })
    versionListing.objects.forEach(o => {
      console.log(`${o.name}, ${o.versionId}`)
    })
    versionListing.deleteMarker.forEach(o => {
      console.log(`${o.name}, ${o.versionId}`)
    })
    nextKeyMarker = versionListing.NextKeyMarker;
    nextVersionMarker = versionListing.NextVersionIdMarker;
  } while (versionListing.isTruncated);
}

getObjectVersionsByPrefix();

List the versions of a specified number of objects

The following sample code provides an example on how to list the versions of a specified number of 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 the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

async function getObjectVersionByNumber() {
  // Specify to return up to 100 object versions. 
  const versionListing = await client.getBucketVersions({
    "max-keys": 100,
  });
  // Display the version IDs of the returned object versions. If versioning is not enabled for the bucket, the version IDs of the returned objects are none. 
  versionListing.objects.forEach((o) => {
    console.log(`${o.name}, ${o.versionId}`);
  });
  versionListing.deleteMarker.forEach((o) => {
    console.log(`${o.name}, ${o.versionId}`);
  });
}

getObjectVersionByNumber();

List objects by directory

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 a directory. By default, an object whose name ends with a forward slash (/) is displayed as a directory in the OSS console.

You can specify the delimiter and prefix parameters in the request to list objects by directory.

  • If you set prefix to a directory name in the request, objects and subdirectories whose names contain the specified prefix are listed.

  • If you specify a prefix and set delimiter to a forward slash (/) in the request, 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 a bucket contains the following objects: oss.jpg, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. The forward slash (/) is specified as the directory delimiter. The following examples describe how to list objects in simulated directories in the bucket.

List versions of objects in the root directory of the bucket

The following sample code provides an example on how to list the versions of objects in the root directory of the bucket:

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 the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Set the delimiter parameter to a forward slash (/) to list the versions of objects and the names of subdirectories in the root directory. 
async function getRootObjectVersions() {
  let nextKeyMarker = null;
  let nextVersionMarker = null;
  let versionListing = null;
  do {
    versionListing = await client.getBucketVersions({
      keyMarker: nextKeyMarker,
      versionIdMarker: nextVersionMarker,
      delimiter: "/",
    });
    nextKeyMarker = versionListing.NextKeyMarker;
    nextVersionMarker = versionListing.NextVersionIdMarker;
    console.log(versionListing);
  } while (versionListing.isTruncated);
}

getRootObjectVersions();

List objects and subdirectories in a directory

The following sample code provides an example on how to list the objects and the subdirectories in a directory of the bucket:

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 the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// Configure the prefix parameter to list all objects and subdirectories in the fun directory. Set the delimiter parameter to a forward slash (/). 
async function getObjectVersionsByPrefixAndDirectory() {
  let nextKeyMarker = null;
  let nextVersionMarker = null;
  let versionListing = null;
  let prefix = "foo/";
  do {
    versionListing = await client.getBucketVersions({
      keyMarker: nextKeyMarker,
      versionIdMarker: nextVersionMarker,
      prefix,
      delimiter: "/",
    });
    nextKeyMarker = versionListing.NextKeyMarker;
    nextVersionMarker = versionListing.NextVersionIdMarker;
    console.log(versionListing);
  } while (versionListing.isTruncated);
}

getObjectVersionsByPrefixAndDirectory();

References

For more information about the API operation that you can call to list objects, see ListObjectVersions (GetBucketVersions).