PutObjectCommand

The PutObjectCommand is used to upload a new object or update an existing object in your DID Space. This command is versatile and can handle various data types, such as files, strings, or buffers, making it the primary method for adding content to your space.

Usage Scenario#

You should use PutObjectCommand whenever you need to:

  • Upload a new file (e.g., an image, a document, or a configuration file).
  • Create a folder by providing a key that ends with a / and no data.
  • Update the content or metadata of an existing file.

Input#

The PutObjectCommand requires the following input parameters to specify the object's location, content, and metadata.

key
string
required
The unique identifier for the object, which can be a file path or a folder name. For example, 'path/to/my-file.txt' or 'my-folder/'.

data
Data
The content of the object. This can be a string, Buffer, Blob, or any other compatible data type. This field is optional if you are creating an empty folder.

hash
string
An optional hash of the object's content, typically an IPFS v1 CID. This can be used to verify data integrity upon upload.

metadata
Record<string, any>
An optional object to store custom metadata associated with the object. This is useful for storing application-specific information like content type, author, or custom tags.

Output#

The command returns a standard output object after the operation is complete.

statusCode
number
The HTTP status code of the response. A value of 200 indicates a successful upload.

statusMessage
string
The HTTP status message corresponding to the status code.

data
void
This command does not return any data in the response body.

Example: Uploading a Text File#

Here's a complete example of how to initialize the SpaceClient and use PutObjectCommand to upload a simple text file.

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 {

See all 5 lines

Example Response

Response

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

In this example, a file named greetings.txt with the content "Hello, DID Space!" is uploaded to the root of the space. We also include custom metadata to specify the content type and the source application.

Best Practices#

  • Use Metadata: Attaching metadata to your objects is a great way to store additional context without altering the object's content. This can be very useful for filtering, organizing, and processing files later on.
  • Handling Large Files: The SDK handles the complexities of multipart uploads for you. Simply provide the data, and the client will manage the streaming and transfer efficiently.
  • Error Handling: Always check the statusCode in the output to confirm that the upload was successful. A 200 status code means success, while other codes indicate potential issues that your application should handle.
Object Commands
GetObjectCommand