淘宝开放平台

列举方法

您可以调用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方法

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

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

通过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

对象存储 OSS

列举指定Bucket下的所有文件

列举方法

简单列举文件

列举指定个数的文件

列举指定前缀的文件

列举指定文件名后的文件

分页列举所有文件

列举结果返回文件owner信息

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

FAQ