Object Storage Service:オブジェクトの一覧表示

変更方法

listまたはlistV2メソッドを呼び出して、バケット内の最大1,000個のオブジェクトを一度に一覧表示できます。 さまざまな方法でオブジェクトを一覧表示するパラメーターを設定できます。 たとえば、特定の開始位置からオブジェクトを一覧表示したり、特定のディレクトリ内のオブジェクトとサブディレクトリを一覧表示したり、ページごとにオブジェクトを一覧表示したりするようにパラメーターを設定できます。 次のセクションでは、listメソッドとlistV2メソッドの違いについて説明します。

• listメソッドを呼び出してオブジェクトを一覧表示すると、デフォルトでオブジェクト所有者に関する情報が返されます。

• listV2メソッドを呼び出してオブジェクトを一覧表示する場合、fetch-ownerパラメーターを設定して、応答にオブジェクト所有者に関する情報を含めるかどうかを指定する必要があります。

  説明

  バージョン管理されたバケット内のオブジェクトを一覧表示するには、listV2メソッドを呼び出すことを推奨します。

次の表に、listメソッドとlistV2メソッドを呼び出してオブジェクトを一覧表示するときに設定できるパラメーターを示します。

• listメソッドを呼び出してオブジェクトを一覧表示する

  次の表に、listメソッドを呼び出してオブジェクトを一覧表示するときに設定できるパラメーターを示します。

  パラメーター	タイプ	説明
  prefix	String	リストされたオブジェクトの名前に含める必要があるプレフィックス。
  delimiter	String	オブジェクトを名前でグループ化するために使用される文字。
  marker	String	リスト操作の開始元となるオブジェクトの名前。 このパラメーターを指定すると、markerパラメーターの値の後に名前がアルファベット順に表示されるオブジェクトが返されます。
  max-keys	番号 | 文字列	返されるオブジェクトの最大数。
  encoding-type	'url' |''	レスポンス内のオブジェクト名がURLエンコードされていることを指定します。

• listV2メソッドを呼び出してオブジェクトを一覧表示する

  次の表に、listV2メソッドを呼び出してオブジェクトを一覧表示するときに設定できるパラメーターを示します。

  パラメーター	タイプ	説明
  prefix	String	リストされたオブジェクトの名前に含める必要があるプレフィックス。
  continuation-token	String	オブジェクトリストの取得元の位置を指定するトークン。
  delimiter	String	オブジェクトを名前でグループ化するために使用される文字。
  max-keys	番号 | 文字列	返されるオブジェクトの最大数。
  start-after	String	リスト操作の開始元となるオブジェクトの名前。 このパラメーターを指定すると、start-afterパラメーターの値のアルファベット順の後に名前が表示されるオブジェクトが返されます。
  fetch-owner	Boolean	レスポンスにオブジェクト所有者に関する情報を含めるかどうかを指定します。
  encoding-type	'url' |''	レスポンス内のオブジェクト名がURLエンコードされていることを指定します。

単純なリストを使用してオブジェクトをリストする

次のサンプルコードでは、指定したバケット内のオブジェクトを一覧表示する方法の例を示します。 デフォルトでは、最大100個のオブジェクトが一覧表示されます。

• listメソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
      // By default, if no parameter is specified, up to 100 objects can be returned. 
      const result = await client.list();
      console.log(result);
  }
  
  list();

• listV2メソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
      // By default, if no parameter is specified, up to 100 objects can be returned. 
      const result = await client.listV2();
      console.log(result);
  }
  
  list();

バケット内の指定数のオブジェクトを一覧表示する

次のサンプルコードでは、max-keysパラメーターを設定して、バケット内の指定した数のオブジェクトを一覧表示する方法の例を示します。

• listメソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
      const result = await client.list({
          // Specify that the first 10 objects in alphabetical order are returned. 
        "max-keys": 10
    });
      console.log(result);
  }
  
  list();

• listV2メソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
      const result = await client.listV2({
          // Specify that the first 10 objects in alphabetical order are returned. 
        "max-keys": 10
    });
      console.log(result);
  }
  
  list();

指定されたプレフィックスを名前に含むオブジェクトのリスト

次のサンプルコードでは、prefixパラメーターを設定して、名前に指定されたプレフィックスが含まれるオブジェクトをバケットに一覧表示する方法の例を示します。

• listメソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
    const result = await client.list({
      // List 10 objects. 
      "max-keys": 10,
      // List objects whose names contain the foo/ prefix. 
      prefix: 'foo/'
    });
    console.log(result);
  }
  
  list();

• listV2メソッドを呼び出してオブジェクトを一覧表示する

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
    const result = await client.listV2({
      // List 10 objects. 
      "max-keys": 10,
      // List objects whose names contain the foo/ prefix. 
      prefix: 'foo/'
    });
    console.log(result);
  }
  
  list();

指定されたオブジェクト名の後に名前がアルファベット順であるオブジェクトを一覧表示する

次のサンプルコードでは、markerまたはstartAfterパラメーターで指定された文字列の後に名前がアルファベット順に表示されるオブジェクトを一覧表示する方法の例を示します。

• listメソッドを呼び出してオブジェクトを一覧表示する

  リスト操作の開始元となるオブジェクトの名前は、markerパラメーターで指定します。

  const OSS = require('ali-oss');
  
  const client = new OSS({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  // List the objects whose names are alphabetically after the object name test. By default, up to 100 objects are listed. 
  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({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
    const result = await client.listV2({
      // List the objects and subfolders whose names are alphabetically after a/b in the a/ folder. 
      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({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  let marker = null; 
  
  // List up to 20 objects on each page. 
  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({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  async function list () {
    let continuationToken = null;
    // List up to 20 objects on each page. 
    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({
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. 
  bucket: 'yourbucketname'
});

// By default, the information about the object owners is not listed. To include the object owner information in the response, you must set the fetch-owner parameter to true. 
async function list () {
  const result = await client.listV2({
    'fetch-owner': true
  });
  console.log(result.objects);
}

list();

指定したフォルダ内のオブジェクトとサブフォルダの一覧表示

OSSはフラット構造を使用してオブジェクトを格納します。 ディレクトリは、名前がスラッシュ (/) で終わるゼロバイトのオブジェクトです。 このオブジェクトをアップロードおよびダウンロードできます。 デフォルトでは、名前がスラッシュ (/) で終わるオブジェクトは、OSSコンソールにディレクトリとして表示されます。 ディレクトリの作成に使用する完全なサンプルコードについては、『GitHub』をご参照ください。

• リクエストでプレフィックスをディレクトリ名に設定すると、プレフィックスを含む名前のオブジェクトとサブディレクトリが一覧表示されます。

• リクエストでプレフィックスを指定し、区切り文字をスラッシュ (/) に設定すると、ディレクトリ内で指定されたプレフィックスで始まる名前のオブジェクトとサブディレクトリが一覧表示されます。 各サブディレクトリは、CommonPrefixesで単一の結果要素としてリストされます。 これらのサブディレクトリ内のオブジェクトおよびディレクトリはリストされません。

次のオブジェクトがバケットに格納されているとします。

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({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  // Call the listDir function and configure different prefixes to list the required objects. 
  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/');
  // Expected result:
  // SubDir: foo/bar/
  // SubDir: foo/hello/
  // Object: foo/x
  // Object: foo/y
  
  listDir('foo/bar/');
  // Expected result:
  // Object: foo/bar/a
  // Object: foo/bar/b
  
  listDir('foo/hello/C/');
  // Expected result:
  // 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({
    // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
    region: 'yourregion',
    // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
    // Specify the name of the bucket. 
    bucket: 'yourbucketname'
  });
  
  // Call the listV2Dir function and configure different prefixes to list the required objects. 
  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/');
  // Expected result:
  // SubDir: foo/bar/
  // SubDir: foo/hello/
  // Object: foo/x
  // Object: foo/y
  
  listDir('foo/bar/');
  // Expected result:
  // Object: foo/bar/a
  // Object: foo/bar/b
  
  listDir('foo/hello/C/');
  // Expected result:
  // Object: foo/hello/C/1
  // Object: foo/hello/C/2
  // ...
  // Object: foo/hello/C/9999

関連ドキュメント

• オブジェクトの一覧表示に使用する完全なサンプルコードについては、『GitHub』をご参照ください。

• オブジェクトを一覧表示するために呼び出すAPI操作の詳細については、「ListObjects (GetBucket) 」および「ListObjectsV2 (GetBucketV2) 」をご参照ください。