文档

Node.js列举文件

更新时间:

本文介绍如何列举指定存储空间下(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方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
        // 不带任何参数,默认最多返回100个文件。
        const result = await client.list();
        console.log(result);
    }
    
    list();
  • 通过listV2方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
        // 不带任何参数,默认最多返回100个文件。
        const result = await client.listV2();
        console.log(result);
    }
    
    list();

列举指定个数的文件

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

  • 通过list方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
        const result = await client.list({
            // 设置按字母排序最多返回前10个文件。
          "max-keys": 10
      });
        console.log(result);
    }
    
    list();
  • 通过listV2方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
        const result = await client.listV2({
            // 设置按字母排序最多返回前10个文件。
          "max-keys": 10
      });
        console.log(result);
    }
    
    list();

列举指定前缀的文件

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

  • 通过list方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const result = await client.list({
        // 列举10个文件。
        "max-keys": 10,
        // 列举文件名中包含前缀foo/的文件。
        prefix: 'foo/'
      });
      console.log(result);
    }
    
    list();
  • 通过listV2方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const result = await client.listV2({
        // 列举10个文件。
        "max-keys": 10,
        // 列举文件名中包含前缀foo/的文件。
        prefix: 'foo/'
      });
      console.log(result);
    }
    
    list();

列举指定文件名后的文件

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

  • 通过list方法

    参数marker代表文件名称。

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    // 列举字典序排在test之后的文件。默认列举100个文件。
    const marker = 'test'
    async function list () {
      const result = await client.list({
        marker
      });
      console.log(result);
    }
    
    list();
  • 通过listV2方法

    startAfter代表文件名称。

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
      const 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方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    let marker = null; 
    
    // 每页列举20个文件。
    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();
  • 通过listV2方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    async function list () {
      let continuationToken = null;
      // 每页列举20个文件。
      const maxKeys = 20;
      do {
        const result = await client.listV2({
          'continuation-token': continuationToken,
          'max-keys': maxKeys
          });
        continuationToken = result.nextContinuationToken;
            console.log(result);
      }while(continuationToken)
    }
    
    list();

列举结果返回文件owner信息

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

const OSS = require('ali-oss');

const client = new OSS({
  // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourregion',
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // yourbucketname填写存储空间名称。
  bucket: 'yourbucketname'
});

// 默认列举的文件信息中不包含owner信息。如需包含owner信息,fetch-owner参数取值为true。
async function list () {
  const 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方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    // 调用listDir函数,通过设置不同的文件前缀列举不同的目标文件。
    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/');
    // 预期返回如下:
    // 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方法

    const OSS = require('ali-oss');
    
    const client = new OSS({
      // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
      region: 'yourregion',
      // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // yourbucketname填写存储空间名称。
      bucket: 'yourbucketname'
    });
    
    // 调用listV2Dir函数,通过设置不同的文件前缀列举不同的目标文件。
    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/');
    // 预期返回
    // 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

相关文档

  • 本页导读 (1)
文档反馈