Append upload lets you add content to the end of an appendable object using the AppendObject operation. Unlike simple upload, which replaces an object entirely, append upload suits scenarios where data grows incrementally—such as log streaming or real-time feeds.
Prerequisites
Before you begin, ensure that you have:
An OSS bucket with cross-origin resource sharing (CORS) rules configured to expose the
x-oss-next-append-positionresponse header. Without this header, the Browser.js SDK cannot retrieve the next append position, and the upload fails. For configuration steps, see Set cross-origin resource sharing.An OSSClient instance. This topic uses an instance created with an OSS endpoint. To create one using a custom domain or Security Token Service (STS), see Initialization or Configuration examples for common scenarios.
Permissions
By default, an Alibaba Cloud account has full permissions. RAM users and RAM roles have no permissions by default and must be granted access via RAM Policy or Bucket policies.
| API | Required action | When |
|---|---|---|
| AppendObject | oss:PutObject | Always required for append upload |
| AppendObject | oss:PutObjectTagging | Required when setting object tags via x-oss-tagging |
How it works
The first call to client.append() creates a new appendable object and returns a nextAppendPosition value. Each subsequent call must pass this value as the position option, which tells OSS where to write the next chunk.
If the position does not match the current object length, OSS returns a PositionNotEqualToLength error.
Object type rules:
| Condition | Result |
|---|---|
| Object does not exist | AppendObject creates a new appendable object |
| Object is appendable and position matches current length | Content is appended to the end of the object |
| Object is appendable but position does not match current length | PositionNotEqualToLength is returned |
| Object is not appendable (for example, a Normal object uploaded via simple upload) | ObjectNotAppendable is returned |
Perform an append upload
The following example shows how to perform two sequential append operations from a browser. The first call creates the appendable object; the second call appends additional data using the position returned by the first call.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
<script src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.17.1.min.js"></script>
</head>
<body>
<input type="file" id="file" />
<button id="upload">Upload</button>
<script>
const upload = document.getElementById("upload");
const client = new OSS({
// Set the region where your bucket is located. For example: oss-cn-hangzhou
region: 'yourRegion',
authorizationV4: true,
// AccessKey pair obtained from STS
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// Security token obtained from STS
stsToken: 'yourSecurityToken',
bucket: 'examplebucket'
});
upload.addEventListener("click", async () => {
const target = file.files[0];
// First append: creates the appendable object at examplefile.txt.
// The result includes nextAppendPosition for the next operation.
const result = await client.append("examplefile.txt", target);
// Second append: appends data starting at nextAppendPosition.
await client.append("123", result, {
position: result.nextAppendPosition,
});
});
</script>
</body>
</html>Replace the following placeholders with your actual values:
| Placeholder | Description |
|---|---|
yourRegion | The region ID of your bucket, for example, oss-cn-hangzhou |
yourAccessKeyId | The AccessKey ID obtained from STS |
yourAccessKeySecret | The AccessKey secret obtained from STS |
yourSecurityToken | The security token obtained from STS |
examplebucket | Your bucket name |
What's next
For the complete sample code, see GitHub examples.
For the AppendObject API reference, see AppendObject.