Upload Object
Updated at:2025-11-03
Simplest upload
Basic workflow
- Initialize an instance of the BOSClient class.
- Calling the BOSClient.putObject() method supports uploading an object as a binary string.
- An ETag is returned immediately after a successful upload.
Example code
Plain Text
1let etag: string;
2try {
3 etag = await bosClient.putObject(<bucketName>, <objectName>, <buf>);
4 logger.info(`put object success, etag:${etag}`);
5} catch (bosResponse) {
6 logger.error(`errCode: ${bosResponse.error.code}`)
7 logger.error(`requestId: ${bosResponse.error.requestId}`)
8 logger.error(`errMessage: ${bosResponse.error.message}`)
9 logger.error(`statusCode: ${bosResponse.statusCode}`)
10}
Parameter description
| Parameters | Description |
|---|---|
| bucketName | Bucket name |
| objectName | Object name |
| buf | Binary stream, of type ArrayBuffer |
Set object's HTTP header or tag
BOS allows setting Http Headers when uploading an object.
Basic workflow
- Set instances of the BasicMeta class and the TagConf class.
- Set different Headers and tags as needed.
- Add the set meta parameter to the putObject() function.
Example code
Plain Text
1let args = new BasicMeta();
2let userMeta = new TreeMap<string, string>();
3userMeta.set("region", "bj");
4userMeta.set("type", "test");
5 args.userMeta = userMeta; // User-defined metadata, but the total size of all user meta must not exceed 2 KB.
6 args.cacheControl = "private"; // Cache settings for downloading the object. Common values include private, no-cache, max-age, must-revalidate
7 args.contentDisposition = "inline"; // Set whether the browser downloads the file; available values are inline, attachment; filename="download.txt"
8 args.storageClass = "COLD"; // Storage class
9 args.expires = "300"; // Used to set the cache expiration time when an object is downloaded. If no time is set, BOS will default the cache expiration time to three days.
10 args.trafficLimit = 8192000; // Speed limit for a single link, with a value range of 819,200-838,860,800 in bit/s, i.e., 100 KB/s-100 MB/s
11let tagConf = new TagConf();
12 let tag1 = new Tag(); // Tag setting
13tag1.tagKey = "a";
14tag1.tagValue = "b";
15let tag2 = new Tag();
16tag1.tagKey = "c";
17tag1.tagValue = "d";
18tagConf.tags = [tag1, tag2];
19try {
20 await bosClient.putObject(<bucketName>, <objectName>, <buf>, <args>, <tagConf>);
21} catch (bosResponse) {
22 logger.error(`errCode: ${bosResponse.error.code}`)
23 logger.error(`requestId: ${bosResponse.error.requestId}`)
24 logger.error(`errMessage: ${bosResponse.error.message}`)
25 logger.error(`statusCode: ${bosResponse.statusCode}`)
26}
Upload object in append mode
BOS supports AppendObject, a feature for uploading files in append mode, ideal for use cases such as log appending, live streaming, and real-time video file uploads. Objects created using AppendObject are Appendable Objects and support data appending. However, objects uploaded using PutObject are Normal Objects and do not allow data appending. The size limit for AppendObject ranges from 0 to 5GB.
Example code
Plain Text
1// Read data from the file
2 // First append
3let appendObjectResult: AppendObjectResult;
4try {
5 // First append
6 appendObjectResult = await bosClient.appendObject(<bucketName>, <objectName>, <buf>);
7 logger.info(`create append object success`);
8 let args = new AppendObjectArgs(); // Parameters for the next append wrilet args = new AppendObjectArgs(); // Parameters for the next append writete
9 for (let i = 0; i < 100; ++i) {
10 args.offset = appendObjectResult.nextAppendOffset as number; // Offset for this append write
11 try {
12 appendObjectResult = await bosClient.appendObject(<bucketName>, <objectName>, <buf>, <args>);
13 logger.info(`append object success, ${i} times`);
14 } catch (bosResponse) {
15 logger.error(`errCode: ${bosResponse.error.code}`)
16 logger.error(`requestId: ${bosResponse.error.requestId}`)
17 logger.error(`errMessage: ${bosResponse.error.message}`)
18 logger.error(`statusCode: ${bosResponse.statusCode}`)
19 }
20 }
21} catch (bosResponse) {
22 logger.error(`errCode: ${bosResponse.error.code}`)
23 logger.error(`requestId: ${bosResponse.error.requestId}`)
24 logger.error(`errMessage: ${bosResponse.error.message}`)
25 logger.error(`statusCode: ${bosResponse.statusCode}`)
26}
Parameter description
| Parameters | Description |
|---|---|
| bucketName | Bucket name |
| objectName | Object name |
| buf | Binary stream, of type ArrayBuffer |
| args | Parameters for append write: instance of the AppendObjectArgs class |
Complete code
Plain Text
1import fs from '@ohos.file.fs';
2import TreeMap from '@ohos.util.TreeMap';
3import { logger, Credential, BosClient, ClientOptions} from "bos"
4import { BasicMeta, TagConf, Tag, AppendObjectResult, AppendObjectArgs } from "bos/src/main/ets/bos/api/DataType"
5
6 let credential = new Credential(AccessKeyID, SecretAccessKey, Token); //Temporary AK/SK and Token returned by STS
7let clientOptions = new ClientOptions();
8 clientOptions.endpoint = "bj.bcebos.com"; //Pass in the domain name of the region where the bucket is located
9 let bosClient = new BosClient(credential, clientOptions); // Create BosClient
10let bucketName = "test-bucket-harmony";
11let objectName = "test-put-object";
12 // Create a temporary file
13let cacheDir = getContext().cacheDir;
14let path = cacheDir + '/test.txt';
15let file = fs.openSync(path, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE | fs.OpenMode.TRUNC)
16fs.writeSync(file.fd, "Hello BOS");
17fs.fsyncSync(file.fd);
18fs.closeSync(file.fd);
19
20 file = fs.openSync(path, fs.OpenMode.READ_ONLY); // Open the file synchronously
21 let stat = fs.lstatSync(path); //Get file information
22 let buf = new ArrayBuffer(stat.size); //Construct ArrayBuffer
23 fs.readSync(file.fd, buf); // Read file content
24fs.fsyncSync(file.fd);
25fs.closeSync(file.fd);
26let etag: string;
27try {
28 etag = await bosClient.putObject(bucketName, objectName, buf); //Upload object
29 logger.info(put object success, etag:${etag}); // Print etag
30} catch (bosResponse) {
31 logger.error(`errCode: ${bosResponse.error.code}`)
32 logger.error(`requestId: ${bosResponse.error.requestId}`)
33 logger.error(`errMessage: ${bosResponse.error.message}`)
34 logger.error(`statusCode: ${bosResponse.statusCode}`)
35}
36
37let args = new BasicMeta();
38let userMeta = new TreeMap<string, string>();
39userMeta.set("region", "bj");
40userMeta.set("type", "test");
41 args.userMeta = userMeta; // User-defined metadata, but the total size of all user meta must not exceed 2 KB.
42 args.cacheControl = "private"; // Cache settings for downloading the object. Common values include private, no-cache, max-age, must-revalidate
43 args.contentDisposition = "inline"; // Set whether the browser downloads the file; available values are inline, attachment; filename="download.txt"
44 args.storageClass = "COLD"; // Storage class
45 args.expires = "300"; // Used to set the cache expiration time when an object is downloaded. If no time is set, BOS will default the cache expiration time to three days.
46 args.trafficLimit = 8192000; // Speed limit for a single link, with a value range of 819,200-838,860,800 in bit/s, i.e., 100 KB/s-100 MB/s
47let tagConf = new TagConf();
48 let tag1 = new Tag(); // Tag setting
49tag1.tagKey = "a";
50tag1.tagValue = "b";
51let tag2 = new Tag();
52tag1.tagKey = "c";
53tag1.tagValue = "d";
54tagConf.tags = [tag1, tag2];
55try {
56 await bosClient.putObject(bucketName, objectName, buf, args, tagConf);
57} catch (bosResponse) {
58 logger.error(`errCode: ${bosResponse.error.code}`)
59 logger.error(`requestId: ${bosResponse.error.requestId}`)
60 logger.error(`errMessage: ${bosResponse.error.message}`)
61 logger.error(`statusCode: ${bosResponse.statusCode}`)
62}
63
64 // Upload the object by means of append write
65let appendObjectResult: AppendObjectResult;
66try {
67 // First append
68 appendObjectResult = await bosClient.appendObject(bucketName, objectName, buf);
69 logger.info(`create append object success`);
70 let args = new AppendObjectArgs(); // Parameters for the next append wrilet args = new AppendObjectArgs(); // Parameters for the next append writete
71 // Test multiple appends
72 for (let i = 0; i < 100; ++i) {
73 args.offset = appendObjectResult.nextAppendOffset as number; // Offset for this append write
74 try {
75 appendObjectResult = await bosClient.appendObject(bucketName, objectName, buf, args);
76 logger.info(`append object success, ${i} times`);
77 } catch (bosResponse) {
78 logger.error(`errCode: ${bosResponse.error.code}`)
79 logger.error(`requestId: ${bosResponse.error.requestId}`)
80 logger.error(`errMessage: ${bosResponse.error.message}`)
81 logger.error(`statusCode: ${bosResponse.statusCode}`)
82 }
83 }
84} catch (bosResponse) {
85 logger.error(`errCode: ${bosResponse.error.code}`)
86 logger.error(`requestId: ${bosResponse.error.requestId}`)
87 logger.error(`errMessage: ${bosResponse.error.message}`)
88 logger.error(`statusCode: ${bosResponse.statusCode}`)
89}
