GetObjectCommand | ArcBlock

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 可讀流。您可以將此流傳輸到檔案、另一個流，或直接處理其資料區塊。

使用範例

此範例示範如何從您的 DID Space 下載物件並將其儲存為本地檔案。它使用 Node.js 的 stream/promises 模組中的 pipeline 函數，以更簡潔、更穩健的方式處理流。

使用 Pipeline 下載物件

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 是一個流物件，而不是實際的檔案內容。

回應結構

{
  "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 區塊來進行更清晰、更可靠的錯誤管理。