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

GetObjectCommand

GetObjectCommand は、DID Space からオブジェクトを取得またはダウンロードするために使用されます。オブジェクトのコンテンツは読み取り可能なストリームとして返されるため、メモリを過剰に消費することなく、あらゆるサイズのファイルを効率的に処理できます。

これは、アプリケーションのダウンロード機能で使用するコマンドです。

入力

このコマンドは、取得するオブジェクトを指定するために単一のパラメータを必要とします。

  • key string (required) — ダウンロードするオブジェクトの一意のキー（パスとファイル名）。例：'photos/profile.jpg' または 'documents/report.pdf'。

出力

リクエストが成功すると、このコマンドはステータス、ヘッダー、およびデータストリームとしてのオブジェクトのコンテンツを含むオブジェクトを返します。

  • statusCode number — レスポンスの HTTP ステータスコード。値 200 は成功を示します。
  • statusMessage string — ステータスコードに対応する HTTP ステータスメッセージ。
  • headers RawAxiosResponseHeaders | AxiosResponseHeaders — HTTP レスポンスヘッダーを含むオブジェクト。これには 'content-type'、'content-length' などのメタデータが含まれることがあります。
  • data Readable — オブジェクトのデータを含む Node.js の Readable ストリーム。このストリームをファイルや別のストリームにパイプしたり、そのチャンクを直接処理したりできます。

使用例

この例では、DID Space からオブジェクトをダウンロードし、ローカルファイルとして保存する方法を示します。Node.js の stream/promises モジュールの pipeline 関数を使用して、より簡潔で堅牢な方法でストリームを処理します。

pipeline を使用したオブジェクトのダウンロード

typescript
import { SpaceClient, GetObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import fs from 'fs';
import path from 'path';
import { pipeline } from 'stream/promises';

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

// 2. ダウンロードするオブジェクトのキーとローカルファイルパスを定義
const objectKey = 'path/to/your/file.txt';
const localFilePath = path.join(__dirname, 'downloaded_file.txt');

async function downloadObject() {
  try {
    // 3. GetObjectCommand を作成して送信
    const command = new GetObjectCommand({ key: objectKey });
    const output = await client.send(command);

    // 4. リクエストが成功したかを確認
    if (output.statusCode === 200 && output.data) {
      console.log(`Successfully started downloading ${objectKey}`);

      // 5. ファイルを保存するための書き込み可能ストリームを作成
      const writer = fs.createWriteStream(localFilePath);

      // 6. pipeline を使用して効率的にデータを転送し、エラーを処理
      await pipeline(output.data, writer);

      console.log(`File downloaded successfully and saved to ${localFilePath}`);
    } else {
      // ダウンロードが失敗した場合、catch ブロックで捕捉されるようにエラーをスロー
      throw new Error(`Failed to download object. Status: ${output.statusCode}, Message: ${output.statusMessage}`);
    }
  } catch (err) {
    console.error('An error occurred during the download process:', err);
  }
}

downloadObject();

応答例（成功時）

上記のコードの output 変数はこのようになります。data はストリームオブジェクトであり、実際のファイルコンテンツではないことに注意してください。

レスポンス構造

json
{
  "statusCode": 200,
  "statusMessage": "OK",
  "headers": {
    "x-amz-id-2": "...",
    "x-amz-request-id": "...",
    "date": "Wed, 29 May 2024 08:30:00 GMT",
    "last-modified": "Tue, 28 May 2024 10:15:00 GMT",
    "etag": "\"...\"",
    "x-amz-server-side-encryption": "AES256",
    "accept-ranges": "bytes",
    "content-type": "application/octet-stream",
    "server": "SpaceServer",
    "content-length": "1024"
  },
  "data": "<ReadableStream>"
}

ベストプラクティス

ストリームの処理

GetObjectCommand の主な利点は、ストリーミングを使用することです。これにより、アプリケーションがファイル全体を一度にメモリに読み込むのを防ぐため、特に大きなファイルにとって重要です。data ストリームは常に宛先にパイプして消費してください。

エラー管理

堅牢なストリーム処理のために、例に示すように Node.js の stream/promises モジュールの pipeline 関数を使用することを強くお勧めします。これにより、データフローの自動管理、バックプレッシャーの処理、ストリームチェーンの任意の部分からのエラー伝播が行われ、コードが簡素化されます。これにより、error や finish の手動イベントリスナーが不要になり、標準の try...catch ブロックを使用して、よりクリーンで信頼性の高いエラー管理が可能になります。