全部產品
Search

搜尋本產品

    Object Storage Service：Node.js列舉檔案

    文件中心

    Object Storage Service：Node.js列舉檔案

    更新時間：Nov 01, 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

    相關文檔