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.
If you want to access an OSS bucket from a browser but no CORS rules are configured for the bucket, the browser rejects the request. Therefore, you must configure CORS rules for a bucket if you want to access the bucket from a browser. For more information, see Installation.
In most cases, OSS SDK for Browser.js is used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use temporary access credentials obtained from Security Token Service (STS) to access OSS.
The temporary access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. For more information about how to obtain temporary access credentials, see Use STS for temporary access authorization.
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:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
</head>
<body>
<script>
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",
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Specify the security token that you obtained from STS.
stsToken: 'yourSecurityToken',
// Specify the name of the bucket. Example: examplebucket.
bucket: "examplebucket",
});
async function list(dir) {
try {
// By default, up to 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) {
result = await client.list({ marker: result.nextMarker });
}
// List the objects whose names start with the prefix 'ex'.
result = await client.list({
prefix: "ex",
});
console.log(result);
// List all objects whose names start with the prefix 'ex' and are alphabetically after the 'example' object.
result = await client.list({
prefix: "ex",
marker: "example",
});
console.log(result);
} catch (e) {
console.log(e);
}
}
list();
</script>
</body>
</html>
List objects and subdirectories in a directory
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 of the bucket:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
</head>
<body>
<script>
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',
authorizationV4: true,
// Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Specify the security token that you 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 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();
</script>
</body>
</html>
The following objects are returned:
> 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 you can call to list objects, see GetBucket (ListObjects).