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 块进行更清晰、更可靠的错误管理。