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 上傳簡單文字檔案的完整範例。
Example: Uploading a file
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();範例回應
Response
{
"statusCode": 200,
"statusMessage": "OK",
"data": undefined
}在此範例中，一個名為 greetings.txt、內容為「Hello, DID Space!」的檔案被上傳到空間的根目錄。我們還包含了自訂元資料，以指定內容類型和來源應用程式。
最佳實踐
- 使用元資料：將元資料附加到您的物件上，是在不改變物件內容的情況下儲存額外上下文的好方法。這對於之後篩選、組織和處理檔案非常有用。
- 處理大型檔案：SDK 會為您處理多部分上傳的複雜性。您只需提供資料，客戶端便會有效地管理串流和傳輸。
- 錯誤處理：務必檢查輸出中的
statusCode以確認上傳是否成功。狀態碼200表示成功，而其他代碼則表示您的應用程式應處理的潛在問題。