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

列举方法

您可以调用listlistV2方法,一次性列举某个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方法
    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方法
    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方法
    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方法
    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方法
    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方法
    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代表文件名称。

    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代表文件名称。

    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方法
    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方法
    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信息:

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中有如下文件:

foo/x
foo/y
foo/bar/a
foo/bar/b
foo/hello/C/1
foo/hello/C/2
...
foo/hello/C/9999

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

  • 通过list方法
    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方法
    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