全部产品
Search

搜索本产品

    对象存储 OSS：Node.js列举文件

    文档中心

    对象存储 OSS：Node.js列举文件

    更新时间：Oct 31, 2024

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

      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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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

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

    • 通过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,
  authorizationV4: true,
  // 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,
  authorizationV4: true,
  // 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

    相关文档