すべてのプロダクト
Search

このプロダクト

    Object Storage Service:オブジェクトのリスト (Node.js SDK)

    ドキュメントセンター

    Object Storage Service:オブジェクトのリスト (Node.js SDK)

    最終更新日:Nov 30, 2025

    このトピックでは、Object Storage Service (OSS) バケット内のすべてのオブジェクト、指定された数のオブジェクト、および名前に指定されたプレフィックスを含むオブジェクトをリストする方法について説明します。

    リストメソッド

    list メソッドまたは listV2 メソッドを呼び出すことで、一度にバケット内の最大 1,000 個のオブジェクトをリストできます。パラメーターを指定して、指定された開始点以降のすべてのオブジェクトのリスト、指定されたディレクトリ内のオブジェクトとサブディレクトリのリスト、結果のページネーションなど、さまざまなリスト操作を実行できます。これら 2 つのメソッドの主な違いは次のとおりです：

    • list メソッドは、デフォルトでオーナー情報を返します。

    • listV2 メソッドでは、結果にオーナー情報を含めるために `fetchOwner` を設定する必要があります。

      説明

      バージョン管理が有効になっているバケットの場合は、listV2 操作を使用してオブジェクトをリストしてください。

    以降のセクションでは、list メソッドと listV2 メソッドのパラメーターについて説明します。

    • list メソッドを使用したオブジェクトのリスト

      パラメーターは次のとおりです：

      パラメーター

      タイプ

      説明

      prefix

      string

      指定されたプレフィックスを持つオブジェクトをリストします。

      delimiter

      string

      オブジェクト名をグループ化するために使用される文字。

      marker

      string

      名前がマーカーの辞書順で後にあるオブジェクトをリストします。

      max-keys

      number | string

      返されるオブジェクトの最大数を指定します。

      encoding-type

      'url' | ''

      返されたコンテンツをエンコードします。 エンコーディングタイプを URL に設定します。

    • listV2 メソッドを使用したオブジェクトのリスト

      listV2 のパラメーターは次のとおりです：

      パラメーター

      タイプ

      説明

      prefix

      string

      指定されたプレフィックスを持つオブジェクトをリストします。

      continuation-token

      string

      このトークンからオブジェクトのリストを開始します。

      delimiter

      string

      オブジェクト名をグループ化するために使用される文字。

      max-keys

      number | string

      返されるオブジェクトの最大数を指定します。

      start-after

      string

      `start-after` の値の辞書順で後にあるオブジェクトの返信を開始します。

      fetch-owner

      boolean

      結果にオーナー情報を含めるかどうかを指定します。

      encoding-type

      'url' | ''

      返されたコンテンツをエンコードします。 エンコーディングタイプを URL に設定します。

    シンプルなオブジェクトのリスト

    次のコードは、指定されたバケット内のオブジェクトをリストする方法を示しています。 デフォルトでは、100 個のオブジェクトがリストされます。

    • list メソッドの使用

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

const client = new OSS({
  // yourregion をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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` パラメーターを使用して、バケット内の指定された数のオブジェクトをリストする方法を示しています。

    • list メソッドの使用

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

const client = new OSS({
  // yourregion をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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` パラメーターを使用して、指定されたプレフィックスを持つバケット内のオブジェクトをリストする方法を示しています。

    • list メソッドの使用

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

const client = new OSS({
  // yourregion をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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/b の後にある a/ フォルダ内のオブジェクトとサブディレクトリをリストします。
    delimiter: '/',
    prefix: 'a/',
    'start-after': 'a/b'
  });
  console.log(result.objects, result.prefixes);
}

list();

    ページごとの全オブジェクトのリスト

    次のコードは、指定されたバケット内のすべてのオブジェクトをページごとにリストする方法を示しています。 ページごとにリストするオブジェクトの数は、`max-keys` で指定します。

    • list メソッド

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

const client = new OSS({
  // yourregion をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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();

    リスト結果へのオーナー情報の追加

    次のコードは、リスト結果にオーナー情報を含める方法を示しています：

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

const client = new OSS({
  // yourregion をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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'
});

// デフォルトでは、リストされたオブジェクトの情報にオーナー情報は含まれません。 オーナー情報を含めるには、fetch-owner パラメーターを true に設定します。
async function list () {
  const result = await client.listV2({
    'fetch-owner': true
  });
  console.log(result.objects);
}

list();

    指定されたディレクトリ内のオブジェクトとサブディレクトリのリスト

      バケットに次のオブジェクトが含まれていると仮定します：

      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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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 をバケットが配置されているリージョンに置き換えます。 たとえば、バケットが中国 (杭州) リージョンにある場合は、リージョンを 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

      リファレンス