メインコンテンツへスキップ

ListObjectsCommand

ListObjectsCommand は、DID Space内の指定されたパスからオブジェクト（ファイルまたはディレクトリ）のリストを取得するために使用されます。フラットな（直下の子のみをリストアップ）ディレクトリトラバーサルと、再帰的な（すべてのネストされたアイテムをリストアップ）ディレクトリトラバーサルの両方のオプションを通じて柔軟性を提供します。

このコマンドは、フォルダの内容を表示したり、ファイルブラウザを構築したり、ストレージの特定の部分にあるすべてのファイルを反復処理したりする必要があるアプリケーションにとって不可欠です。

ユースケース

ListObjectsCommand を使用する一般的なシナリオは次のとおりです。

  • ユーザーが保存したファイルをナビゲートするためのファイルエクスプローラーインターフェースを構築する。
  • 最初にリモートオブジェクトをリストアップして、ローカルディレクトリをリモートディレクトリと同期させる。
  • 特定のフォルダ内のすべてのファイルに対してバッチ操作を実行する。
  • アップロードまたは一連のファイル操作後にディレクトリの内容を確認する。

入力パラメータ

コマンドのコンストラクタは、次のプロパティを持つオブジェクトを受け入れます。

  • key string (default: /) — 内容をリストアップしたいディレクトリのパス。省略した場合、デフォルトでルートディレクトリ（'/'）になります。
  • recursive boolean — trueに設定すると、コマンドは指定されたキー以下のすべてのオブジェクトを再帰的にリストアップします。falseまたは未指定の場合、直下の子のみのフラットなリストアップを実行します。
  • ignoreDirectories boolean — trueに設定すると、ディレクトリは結果セットから除外されます。このオプションは 'recursive' が false の場合にのみ有効です。

出力

send メソッドは、コマンドの出力を含むオブジェクトに解決されるプロミスを返します。

  • statusCode number — レスポンスのHTTPステータスコード。200の値は成功を示します。
  • data Object[] — 指定されたキーで見つかったファイルとディレクトリを表すオブジェクトの配列。
    • key string — オブジェクトのフルパスと名前。
    • type 'object' | 'directory' — アイテムのタイプ。
    • size number — オブジェクトのサイズ（バイト単位）。ディレクトリの場合、通常は0です。
    • lastModified string — オブジェクトが最後に変更された日時を示すISO 8601形式の日付文字列。

応答例（成功）

成功応答の例

json
{
  "statusCode": 200,
  "data": [
    {
      "key": "/photos/summer/beach.jpg",
      "type": "object",
      "size": 2048576,
      "lastModified": "2023-10-27T10:00:00.000Z"
    },
    {
      "key": "/photos/summer/mountains/",
      "type": "directory",
      "size": 0,
      "lastModified": "2023-10-26T15:30:00.000Z"
    }
  ]
}

コード例

この例では、SpaceClient を初期化し、ListObjectsCommand を使用してディレクトリの内容をリストアップする方法を示します。

例

typescript
import { SpaceClient, ListObjectsCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function listMyFiles() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/', // リストアップするディレクトリを指定
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully listed objects:');
    if (output.data.length > 0) {
      output.data.forEach((item) => {
        console.log(`- [${item.type}] ${item.key} (Size: ${item.size} bytes)`);
      });
    } else {
      console.log('The directory is empty.');
    }
  } else {
    console.error('Failed to list objects:', output);
  }
}

listMyFiles();

再帰的なリストアップ

/shared-documents/ 内のすべてのファイルとサブディレクトリをリストアップするには、recursive オプションを true に設定します。

再帰的なリストアップ

typescript
async function listAllFilesRecursively() {
  const command = new ListObjectsCommand({
    key: '/shared-documents/',
    recursive: true,
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('All nested objects:');
    output.data.forEach((item) => {
      console.log(`- ${item.key}`);
    });
  } else {
    console.error('Recursive listing failed:', output);
  }
}

listAllFilesRecursively();

ベストプラクティスと一般的なパターン

  • パフォーマンス: 大規模なディレクトリの場合、必要でない限り再帰的なリストアップは避けてください。フラットなリストアップは取得するデータが少ないため、大幅に高速です。
  • ファイルツリーの構築: UIファイルツリーを構築するには、まずルートレベルに対して非再帰的な呼び出しから始めます。次に、ユーザーが各サブディレクトリを展開するたびに、それらに対して後続の非再帰的な呼び出しを行います。あるいは、オブジェクトの総数が管理可能であれば、一度の再帰的な呼び出しでツリー全体の状態を取得することもできます。
  • ファイルのフィルタリング: 特定のディレクトリ内のファイルのみを処理する必要があり（サブディレクトリは不要）、効率的なファイルのみのリストが必要な場合は、非再帰的な呼び出しと ignoreDirectories: true を組み合わせてください。