All Products
Search
Document Center

Object Storage Service:Append upload

Last Updated:Apr 02, 2025

You can call the AppendObject operation to append content to existing appendable objects.

Usage notes

  • In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.

  • In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.

  • In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Configuration examples for common scenarios.

  • If the object to which you want to append content does not exist, the AppendObject operation creates an appendable object.

  • If the object to which you want to append content exists:

    • If the object is an appendable object and the specified position from which the append operation starts is equal to the current object size, the data 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 size, 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 on resources in the account. In contrast, RAM users and RAM roles associated with an Alibaba Cloud account initially have no permissions. To manage resources by using a RAM user or role, you must grant the required permissions via RAM policies or Bucket policies.

API

Action

Description

AppendObject

oss:PutObject

Uploads an object by appending the content of the object to an existing object.

oss:PutObjectTagging

Specifies the tags of the object by using the x-oss-tagging header when you perform append upload.

Sample code

The following code provides an example on how to upload an object by using append upload:

const OSS = require('ali-oss')

const client = new OSS({
  // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET. 
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the name of the bucket. Example: examplebucket. 
  bucket: 'examplebucket',
});

const headers = {    
  // Specify the access control list (ACL) of the object. 
  'x-oss-object-acl': 'private',
  // Specify the storage class of the object. 
  'x-oss-storage-class': 'Standard',  
  // Specify the server-side encryption method. In this example, SSE-OSS is used. 
  'x-oss-server-side-encryption': 'AES256',  
};

async function append () {
  // Perform the first append upload operation. The position from which the next append operation starts is included in the response. 
  // Specify the full path of the object. Do not include the bucket name in the full path. Example: destfolder/examplefile.txt. 
  // Specify the full path of the local file. The full path contains the suffix. Example: /users/local/examplefile.txt. 
  const result = await client.append('objectName', 'localFile'
  // Specify custom headers and user metadata. 
  //,{headers} 
  )

  // Perform the second append operation. The position from which the next append operation starts is the current length of the object, which is specified by Content-Length. 
  result = await client.append('objectName', 'localFile', {
    position: result.nextAppendPosition
  })
}

append();

References

For more information about the API operation that you can call to perform append upload, see AppendObject.