本文介绍如何列举指定存储空间下（Bucket）的所有文件（Object）、指定个数的文件、指定前缀的文件等。

列举方法

您可以调用list或listV2方法，一次性列举某个Bucket下最多1000个Object。您可以通过指定参数实现多种列举功能，例如通过指定参数列举指定起始位置后的所有文件、列举指定目录下的文件和子目录、以及列举结果分页。这两个接口的主要区别如下：

  • 使用list方法列举文件时，默认返回owner信息。
  • 使用listV2方法列举文件时，需通过fetchOwner指定是否在返回结果中包含owner信息。
    说明 对于开启版本控制的Bucket，建议使用 listV2接口列举文件。

以下分别介绍通过list以及listV2方法列举文件时涉及的参数说明。

  • 通过list方法列举文件

    list涉及参数说明如下：

    参数 类型 描述
    prefix string 列举符合特定前缀的文件。
    delimiter string 对文件名称进行分组的字符。
    marker string 列举文件名在marker之后的文件。
    max-keys number | string 指定最多返回的文件个数。
    encoding-type 'url' | '' 对返回的内容进行编码并指定编码类型为URL。
  • 通过listV2方法列举文件

    listV2涉及参数说明如下：

    参数 类型 描述
    prefix string 列举符合特定前缀的文件。
    continuation-token string 从此token开始获取文件列表。
    delimiter string 对文件名称进行分组的字符。
    max-keys number | string 指定最多返回的文件个数。
    start-after string 设定从start-after之后按字母排序开始返回Object
    fetch-owner boolean 是否在返回结果中包含owner信息 。
    encoding-type 'url' | '' 对返回的内容进行编码并指定编码类型为URL。

简单列举文件

以下代码用于列举指定Bucket的文件，默认列举100个文件。

  • 通过list方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
        // 不带任何参数，默认最多返回100个文件。
        let result = await client.list();
        console.log(result);
    }
     
    list();
  • 通过listV2方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
        // 不带任何参数，默认最多返回100个文件。
        let result = await client.listV2();
        console.log(result);
    }
     
    list();

列举指定个数的文件

以下代码用于通过max-keys参数列举Bucket下指定个数的文件。

  • 通过list方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
        let result = await client.list({
            // 设置按字母排序最多返回前10个文件。
          "max-keys": 10
      });
        console.log(result);
    }
     
    list();
  • 通过listV2方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
        let result = await client.listV2({
            // 设置按字母排序最多返回前10个文件。
          "max-keys": 10
      });
        console.log(result);
    }
     
    list();

列举指定前缀的文件

以下代码用于通过prefix参数列举Bucket中包含指定前缀的文件。

  • 通过list方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
      let result = await client.list({
        // 列举10个文件。
        "max-keys": 10,
        // 列举文件名中包含前缀foo/的文件。
        prefix: 'foo/'
      });
      console.log(result);
    }
     
    list();
  • 通过listV2方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
      let result = await client.listV2({
        // 列举10个文件。
        "max-keys": 10,
        // 列举文件名中包含前缀foo/的文件。
        prefix: 'foo/'
      });
      console.log(result);
    }
     
    list();

列举指定文件名后的文件

以下代码用于列举文件名称字典序排在指定字符串（marker或startAfter）之后的文件。

  • 通过list方法

    参数marker代表文件名称。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    // 列举字典序排在test之后的文件。默认列举100个文件。
    const marker = 'test'
    async function list () {
      let result = await client.list({
        marker
      });
      console.log(result);
    }
     
    list();
  • 通过listV2方法

    startAfter代表文件名称。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
      let result = await client.listV2({
        // 列举a/文件夹下名称在a/b之后的文件及子文件夹。
        delimiter: '/',
        prefix: 'a/',
        'start-after': 'a/b'
      });
      console.log(result.objects， result.prefixes);
    }
     
    list();

分页列举所有文件

以下代码用于分页列举指定Bucket下的所有文件。每页列举的文件个数通过max-keys指定。

  • 通过list方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    let marker = null;
    // 每页列举20个文件。
    const maxKeys = 20;
    async function list () {
      do {
        let result = await client.list({
              marker,
          'max-keys': maxKeys
          });
        marker = result.nextMarker;
            console.log(result);
      }while(marker)
    }
     
    list();
  • 通过listV2方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    async function list () {
      let continuationToken = null;
      // 每页列举20个文件。
      const maxKeys = 20;
      do {
        let result = await client.listV2({
          'continuation-token': continuationToken,
          'max-keys': maxKeys
          });
        continuationToken = result.nextContinuationToken;
            console.log(result);
      }while(continuationToken)
    }
     
    list();

列举结果返回文件owner信息

以下代码用于列举结果中返回文件的owner信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
let OSS = require('ali-oss');
 
let client = new OSS({
  // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
  region: '<Your region>',
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  // 填写Bucket名称。
  bucket: '<Your bucket name>',
});
 
// 默认列举的文件信息中不包含owner信息。如需包含owner信息，fetch-owner参数取值为true。
async function list () {
  let result = await client.listV2({
    'fetch-owner': true
  });
  console.log(result.objects);
}
 
list();

列举指定目录下的文件和子目录

OSS没有文件夹的概念，所有元素都是以文件来存储。创建文件夹本质上来说是创建了一个大小为0并以正斜线（/）结尾的文件。这个文件可以被上传和下载，控制台会对以正斜线（/）结尾的文件以文件夹的方式展示。

通过delimiter和prefix两个参数可以模拟文件夹功能：

  • 如果设置prefix为某个文件夹名称，则会列举以此prefix开头的文件，即该文件夹下所有的文件和子文件夹（目录）均显示为objects。
  • 如果在设置了prefix的情况下，将delimiter设置为正斜线（/），则只列举该文件夹下的文件和子文件夹（目录），该文件夹下的子文件夹（目录）显示为CommonPrefixes，子文件夹下的文件和文件夹不显示。

假设Bucket中有如下文件：

1
2
3
4
5
6
7
8
foo/x
foo/y
foo/bar/a
foo/bar/b
foo/hello/C/1
foo/hello/C/2
...
foo/hello/C/9999

以下代码用于通过list或listV2的方法列举指定目录下的文件和子目录。

  • 通过list方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
     
    // 调用listDir函数，通过设置不同的文件前缀列举不同的目标文件。
    async function listDir(dir) {
      const result = await client.list({
        prefix: dir,
        // 设置正斜线（/）为文件夹的分隔符。
        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
  • 通过listV2方法
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    let OSS = require('ali-oss');
     
    let client = new OSS({
      // region以杭州为例（oss-cn-hangzhou），其他region按实际情况填写。
      region: '<Your region>',
      // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
      accessKeyId: '<Your AccessKeyId>',
      accessKeySecret: '<Your AccessKeySecret>',
      // 填写Bucket名称。
      bucket: '<Your bucket name>',
    });
    // 调用listV2Dir函数，通过设置不同的文件前缀列举不同的目标文件。
    async function listV2Dir(dir) {
      const result = await client.listV2({   
        prefix: dir,
        // 设置正斜线（/）为文件夹的分隔符。
        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