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 上传一个简单的文本文件。
示例：上传文件
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();示例响应
响应
{
"statusCode": 200,
"statusMessage": "OK",
"data": undefined
}在此示例中，一个名为 greetings.txt、内容为 "Hello, DID Space!" 的文件被上传到空间的根目录。我们还包含了自定义元数据，以指定内容类型和源应用程序。
最佳实践
- 使用元数据：将元数据附加到对象是存储额外上下文而无需更改对象内容的好方法。这对于以后筛选、组织和处理文件非常有用。
- 处理大文件：SDK 会为您处理分段上传的复杂性。只需提供数据，客户端就会高效地管理流式传输和传输过程。
- 错误处理：务必检查输出中的
statusCode以确认上传是否成功。状态码200表示成功，而其他代码则表示您的应用程序应处理的潜在问题。