How to append upload using the Harmony SDK - Object Storage Service

You can append content to existing appendable objects. This topic describes how to perform append upload using Object Storage Service (OSS) SDK for Harmony 2.0.

Usage notes

For more information about regions and endpoints, see Regions and endpoints.
If the object to which you want to append content does not exist, an appendable object is created when you call an append upload operation.
If the file already exists:
- If the object is an appendable object and the specified position from which the append operation starts is equal to the current object length, the object is appended to the end of the object.
- If the object is an appendable object and the specified position from which the append operation starts is not equal to the current object length, the PositionNotEqualToLength error is returned.
- If the object is not an appendable object, the ObjectNotAppendable error is returned.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket policies.

API

Action

Definition

AppendObject

oss:PutObject

You can call this operation to upload an object by appending the object to an existing object.

oss:PutObjectTagging

When uploading an object by appending the object to an existing object, if you specify object tags through x-oss-tagging, this permission is required.

Sample code

The following code provides an example on how to perform append upload:

import Client, {RequestError } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from Security Token Service (STS).
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append the content to an OSS object. 
 * Use the appendObject method to append data to a specific object in a specific bucket. 
 */
const appendObject = async () => {
  try {
    // Use the appendObject method to append data to a specific object in a specific bucket.
    // Do not specify the position parameter when you create an appendable object for the first time. Then, specify the position parameter when you perform the append upload operation.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'hello world' // Specify the data that you want to append. In this example, a simple string is appended.
    });

    // Display the append upload results.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the appendObject function to perform the append upload operation.
appendObject();

Common scenarios

Append a local file to an object

The following sample code provides an example on how to append a local file to an object:

import Client, { RequestError } from '@aliyun/oss';
import { fileIo as fs } from '@kit.CoreFileKit';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append content to the object using the local file path. 
 * Use the appendObject method to append the content of a local file to an object in a specific bucket. 
 */
const appendObjectByFile = async () => {
  // Open and read the local file.
  const file=await fs.open('yourFilePath', fs.OpenMode.READ_ONLY); // Specify the path of the local file.

  try {
    // Use the appendObject method to append the content of a local file to an object in a specific bucket.
    // Do not specify the position parameter when you create an appendable object for the first time. Then, specify the position parameter when you perform the append upload operation.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: file, // Specify the local file that you want to append.
    });

    // Display the append upload results.
    console.log(JSON.stringify(res));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  } finally {
    // Close the local file after the operation is complete.
    await fs.close(file);
  }
};

// Call the appendObjectByFile function to perform the append upload operation.
appendObjectByFile();

Specify the position from which the append operation starts

The following sample code provides an example on how to specify the position from which the append operation starts:

import Client, { RequestError, EHeaderKey } from '@aliyun/oss';

// Create an OSSClient instance.
const client = new Client({
  // Specify the AccessKey ID obtained from STS.
  accessKeyId: 'yourAccessKeyId',
  // Specify the AccessKey secret obtained from STS.
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the security token obtained from STS.
  securityToken: 'yourSecurityToken',
  // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
});

// Specify the name of the bucket.
const bucket = 'yourBucketName';
// Specify the name of the object to which you want to append content.
const key = 'yourObjectName';

/**
 * Append the content to an OSS object and specify the position from which the append operation starts. 
 * Use the appendObject method to append data blocks to a specific object in a specific bucket and specify the position from which the append operation starts. 
 */
const appendObjectWithPosition = async () => {
  try {
    // Call the appendObject method to start the first append upload to append the initial data block.
    const res = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'first chunk data', // The first data block.
    });

    // Display the first append upload results.
    console.log(JSON.stringify(res));

    /* Obtain the position from which the next append operation starts.
    const nextAppendPosition = Number(res.origRes.headers[EHeaderKey.X_OSS_NEXT_APPEND_POSITION]);

    // Call the appendObject method to start the second append upload to append the second data block.
    const res1 = await client.appendObject({
      bucket, // Specify the name of the bucket.
      key,    // Specify the name of the object.
      data: 'second chunk data', // The second data block.
      position: nextAppendPosition, // The append position from which the second append starts.
    });

    // Display the second append upload results.
    console.log(JSON.stringify(res1));
  } catch (err) {
    // Capture exceptions during the request.
    if (err instanceof RequestError) {
      // If known types of errors exist, display information, such as the error code, error message, request ID, HTTP status code, and EC.
      console.log('code: ', err.code); // The error code.
      console.log('message: ', err.message); // The error message.
      console.log('requestId: ', err.requestId); // The request ID.
      console.log('status: ', err.status); // The HTTP status code.
      console.log('ec: ', err.ec); // The EC.
    } else {
      // Display other unknown types of errors.
      console.log('unknown error: ', err);
    }
  }
};

// Call the appendObjectWithPosition function to perform the append upload operation to append data blocks.
appendObjectWithPosition();