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

PutObjectCommand

PutObjectCommand は、DID Space に新しいオブジェクトをアップロードしたり、既存のオブジェクトを更新したりするために使用されます。このコマンドは多機能で、ファイル、文字列、バッファなど、さまざまなデータ型を扱うことができるため、スペースにコンテンツを追加する主要な方法となります。

利用シナリオ

以下のような場合に PutObjectCommand を使用してください。

  • 新しいファイル（例：画像、ドキュメント、設定ファイル）をアップロードする。
  • 末尾が / で終わるキーを指定し、データを指定せずにフォルダを作成する。
  • 既存のファイルの内容やメタデータを更新する。

入力

PutObjectCommand は、オブジェクトの場所、コンテンツ、メタデータを指定するために、以下の入力パラメータを必要とします。

  • key string (required) — オブジェクトの一意の識別子で、ファイルパスやフォルダ名を指定できます。例：'path/to/my-file.txt' または 'my-folder/'。
  • data Data — オブジェクトのコンテンツです。これは文字列、Buffer、Blob、またはその他の互換性のあるデータ型を指定できます。空のフォルダを作成する場合、このフィールドはオプションです。
  • hash string — オブジェクトのコンテンツのオプションのハッシュで、通常は IPFS v1 CID を使用します。これは、アップロード時にデータの完全性を検証するために使用できます。
  • metadata Record<string, any> — オブジェクトに関連付けられたカスタムメタデータを格納するためのオプションのオブジェクトです。これは、コンテンツタイプ、作成者、カスタムタグなどのアプリケーション固有の情報を格納するのに役立ちます。

出力

操作が完了すると、コマンドは標準の出力オブジェクトを返します。

  • statusCode number — レスポンスの HTTP ステータスコード。値が 200 の場合はアップロードが成功したことを示します。
  • statusMessage string — ステータスコードに対応する HTTP ステータスメッセージ。
  • data void — このコマンドはレスポンスボディにデータを返しません。

例：テキストファイルのアップロード

以下は、SpaceClient を初期化し、PutObjectCommand を使用して簡単なテキストファイルをアップロードする方法の完全な例です。

例：ファイルのアップロード

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

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

  const command = new PutObjectCommand({
    key: 'greetings.txt',
    data: 'Hello, DID Space!',
    metadata: {
      contentType: 'text/plain',
      source: 'my-application',
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('File uploaded successfully!');
  } else {
    console.error(`Failed to upload file: ${output.statusCode} ${output.statusMessage}`);
  }
}

uploadFile();

レスポンス例

レスポンス

json
{
  "statusCode": 200,
  "statusMessage": "OK",
  "data": undefined
}

この例では、「Hello, DID Space!」という内容の greetings.txt という名前のファイルが、スペースのルートにアップロードされます。また、コンテンツタイプとソースアプリケーションを指定するために、カスタムメタデータも含まれています。

ベストプラクティス

  • メタデータの使用：オブジェクトにメタデータを添付することは、オブジェクトのコンテンツを変更することなく追加のコンテキストを保存する優れた方法です。これは、後でファイルをフィルタリング、整理、処理する際に非常に役立ちます。
  • 大きなファイルの処理：SDK はマルチパートアップロードの複雑さを自動的に処理します。データを指定するだけで、クライアントがストリーミングと転送を効率的に管理します。
  • エラーハンドリング：アップロードが成功したことを確認するために、常に出力の statusCode を確認してください。200 のステータスコードは成功を意味し、その他のコードはアプリケーションが処理すべき潜在的な問題を示します。