Uploading an Object - Append (SDK for Node.js)

If you have any questions during development, post them on the Issues page of GitHub.

Function

This API uploads a file or folder to an existing OBS bucket. You can upload text, pictures, videos, or any other types of files.

This API adds data to the end of a specified object. If there is no object with the same key found in the bucket, a new object is created.

The latest modification time of the object is updated each time an upload is appended.

Restrictions

To upload an object, you must be the bucket owner or have the required permission (obs:object:PutObject in IAM or PutObject in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
To learn about the mappings between OBS regions and endpoints, see Regions and Endpoints.
The name of each object in a bucket must be unique.
If SSE-C is used for server-side encryption, you must carry request headers such as x-obs-server-side-encryption in each append upload.
If SSE-KMS is used for server-side encryption, you only need to carry request headers such as x-obs-server-side-encryption when you first call this API to upload an object and when there is no existing object with the same name in the bucket.
The size of each append upload cannot exceed 5 GB.
The maximum number of append uploads for each appendable object is 10,000.
If the storage class is COLD (Archive), this API cannot be called.
If cross-region replication is configured for a bucket, this API cannot be called.
Objects in parallel file systems are not appendable.
Objects uploaded using ObsClient.putObject, referred to as normal objects, can overwrite objects uploaded using ObsClient.appendObject, referred to as appendable objects. Data cannot be appended to an appendable object anymore once the object has been overwritten by a normal object.
When you upload an object for the first time in appendable mode, an exception will be reported (HTTP status code 409) if a common object with the same name exists.
The ETag returned for an appendable upload is the ETag for the uploaded content, rather than that of the whole object.

Method

ObsClient.appendObject(params)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
Bucket	string	Yes	Explanation: Bucket name. Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets with the same name in the same region, no error will be reported, and the bucket attributes comply with those set in the first creation request. Value range: The value can contain 3 to 63 characters. Default value: None
Key	string	Yes	Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path of the object that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Restrictions: None Value range: The value can contain 1 to 1,024 characters. Default value: None
Position	number	Yes	Explanation: Position where the object data is appended Restrictions: For an object to be appended, the value of position must be set to 0 when the object is uploaded for the first time. For the second append upload, the value of position should be set to the value of NextAppendPosition returned in the response when the first upload is successful. Value range: 0 to (2⁶³ – 1), in bytes Default value: 0
Body	string \| stream.Readable	No	Explanation: Content of the part to upload, which can be in string or stream.Readable form. Restrictions: The object size in a single upload ranges from 0 to 5 GB. To upload files larger than 5 GB, refer to Multipart Upload APIs (SDK for Node.js). Body and SourceFile cannot be used together. If both Body and SourceFile are left blank, the size of the uploaded object is 0 bytes. Value range: None Default value: None
SourceFile	string	No	Explanation: Source file path of the object to be uploaded Restrictions: The content size in a single upload ranges from 0 to 5 GB. Body and SourceFile cannot be used together. If both Body and SourceFile are left blank, the size of the uploaded object is 0 bytes. Offset and SourceFile are used together to specify what data is uploaded from the source file. Value range: None Default value: None
Offset	number	No	Explanation: Start offset of a part in the source file. Restrictions: Offset and SourceFile are used together to specify what data is uploaded from the source file. Value range: A non-negative integer smaller than the size of the object to be uploaded, in bytes Default value: 0
ProgressCallback	function	No	Explanation: Callback function for obtaining the upload progress NOTE: This callback function contains the following parameters in sequence: number of uploaded bytes, total bytes, and used time (in seconds). Restrictions: None Value range: None Default value: None
ContentMD5	string	No	Explanation: Base64-encoded MD5 value of the data to be uploaded. It is used for the OBS server to verify data integrity. Restrictions: Base64-encoded, 128-bit MD5 value of the request body. Value range: Base64-encoded, 128-bit MD5 value of the request body calculated based on the RFC 1864 standard. Example: n58IG6hfM7vqI4K0vnWpog== Default value: None
ACL	AclType	No	Explanation: Access control list (ACL) that can be pre-defined when an object is created. For details about ACLs, see ACLs. Restrictions: This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: See Table 2. Default value: None
WebsiteRedirectLocation	string	No	Explanation: If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL. The request is redirected to object anotherPage.html in the same bucket: WebsiteRedirectLocation:/anotherPage.html The request is redirected to an external URL: WebsiteRedirectLocation:http://www.example.com/ OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation. Restrictions: This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS only supports redirection of objects that are in the root directory. Value range: None Default value: None
ContentType	string	No	Explanation: MIME type of the file to be uploaded. MIME type is a standard way of describing a data type and is used by the browser to decide how to display data. Restrictions: This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: See What Is Content-Type (MIME)? (SDK for Node.js) Default value: If you do not specify this parameter when uploading an object, the SDK determines the object type based on the suffix of the specified object name and automatically assigns a value to this parameter.
ContentLength	int64	No	Explanation: Size of the object to be uploaded. Restrictions: The object size in a single upload ranges from 0 to 5 GB. To upload files larger than 5 GB, refer to Multipart Upload APIs (SDK for Node.js). Value range: 0 GB to 5 GB Default value: If this parameter is not specified, the SDK automatically calculates the size of the object.
SseKms	string	Yes when SSE-KMS is used	Explanation: SSE-KMS is used for encrypting objects on the server side. Restrictions: Currently, only KMS is supported. This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: kms Default value: None
SseKmsKey	string	No	Explanation: ID of the KMS master key when SSE-KMS is used. Restrictions: This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: Valid value formats are as follows: regionID:domainID:key/key_id key_id In the preceding formats: regionID indicates the ID of the region where the key is used. You can obtain it from Regions and Endpoints. domainID indicates the ID of the account that the key is for. To obtain it, see How Do I Get My Account ID and User ID? (SDK for Node.js) key_id indicates the ID of the key created on Data Encryption Workshop (DEW). To obtain it, see Viewing a CMK. Default value: If this parameter is not specified, the default master key will be used. If there is not a default master key, OBS will create one and use it.
SseC	string	Yes when SSE-C is used	Explanation: SSE-C is used for encrypting objects on the server side. Restrictions: Only AES256 is supported. This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: AES256 Default value: None
SseCKey	string	Yes when SSE-C is used	Explanation: Key used for encrypting the object when SSE-C is used Restrictions: A Base64-encoded, 256-bit value, for example, K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= This parameter can only be configured in the first request for append upload. The configurations specified in the first request will be used in subsequent requests by default. Value range: None Default value: None
StorageClass	StorageClassType	No	Explanation: When creating an object, you can use this header to specify the storage class for the object. Restrictions: None Value range: See Table 3. Default value: If this parameter is not specified, the object inherits the storage class of the bucket.
Metadata	object	No	Explanation: Custom metadata of the object to be uploaded. You can add a header starting with x-obs-meta- in the request to define metadata. The custom metadata will be returned in the response when you retrieve the object or query the object metadata. Restrictions: This parameter is valid only for the first append upload. The custom metadata cannot exceed 8 KB in total. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values. The custom metadata keys are case insensitive, but are stored in lowercase in OBS. The key values are case sensitive. Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations. Value range: None Default value: None
GrantRead	string	No	Explanation: ID (domain_id) of an account the READ permission is granted to. The account with the READ permission can read the current object and obtain its metadata. Restrictions: If multiple accounts are authorized, separate them with commas (,). Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js) Default value: None
GrantReadAcp	string	No	Explanation: ID (domain_id) of an account the READ_ACP permission is granted to. The account with the READ_ACP permission can read the ACL of the current object. Restrictions: If multiple accounts are authorized, separate them with commas (,). Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js) Default value: None
GrantWriteAcp	string	No	Explanation: ID (domain_id) of an account the WRITE_ACP permission is granted to. The account with the WRITE_ACP permission can modify the ACL of the current object. Restrictions: If multiple accounts are authorized, separate them with commas (,). Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js) Default value: None
GrantFullControl	string	No	Explanation: ID (domain_id) of an account the FULL_CONTROL permission is granted to. The account with the FULL_CONTROL permission can read the current object, obtain its metadata, and obtain and modify its ACL. Restrictions: If multiple accounts are authorized, separate them with commas (,). Value range: To obtain the account ID, see How Do I Get My Account ID and User ID? (SDK for Node.js) Default value: None
Expires	number	No	Explanation: Expiration time of the object (calculated from the latest modification time of the object). Expired objects are automatically deleted. Restrictions: The value cannot be smaller than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you cannot specify a value less than 10. This parameter can only be configured when uploading an object. Value range: 1 to (2⁶³ - 1), in days Default value: None

**Table 2** AclType
Constant	Default Value	Description
ObsClient.enums.AclPrivate	private	Private read and write A bucket or object can only be accessed by its owner.
ObsClient.enums.AclPublicRead	public-read	Public read and private write If this permission is granted on a bucket, anyone can read the object list, multipart uploads, metadata, and object versions in the bucket. If this permission is granted on an object, everyone can obtain the content and metadata of the object.
ObsClient.enums.AclPublicReadWrite	public-read-write	Public read and write If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions in the bucket and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart upload tasks. If this permission is granted on an object, everyone can obtain the content and metadata of the object.
ObsClient.enums.AclPublicReadDelivered	public-read-delivered	Public read on a bucket as well as the objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart tasks, metadata, and object versions and read the content and metadata of objects in the bucket. NOTE: AclPublicReadDelivered does not apply to objects.
ObsClient.enums.AclPublicReadWriteDelivered	public-read-write-delivered	Public read and write on a bucket as well as the objects in the bucket. If this permission is granted on a bucket, anyone can read the object list, multipart uploads, metadata, and object versions in the bucket and can upload or delete objects, initiate multipart upload tasks, upload parts, assemble parts, copy parts, and abort multipart uploads. They can also read the content and metadata of objects in the bucket. NOTE: AclPublicReadWriteDelivered does not apply to objects.
ObsClient.enums.AclBucketOwnerFullControl	bucket-owner-full-control	If this permission is granted on an object, only the bucket and object owners have the full control over the object. By default, if you upload an object to a bucket of any other user, the bucket owner does not have the permissions on your object. After you grant this policy to the bucket owner, the bucket owner can have full control over your object. For example, if user A uploads object x to user B's bucket, user B does not have the control over object x. If user A sets the bucket-owner-full-control policy for object x, user B then has the control over object x.

**Table 3** StorageClassType
Constant	Default Value	Description
ObsClient.enums.StorageClassStandard	STANDARD	Standard storage class. Features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.
ObsClient.enums.StorageClassWarm	WARM	Infrequent Access storage class. Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but becomes instantly available when needed.
ObsClient.enums.StorageClassCold	COLD	Archive storage class. Used for storing rarely accessed (once a year) data.

Responses

**Table 4** Responses
Type	Description
Table 5 NOTE: This API returns a Promise response, which requires the Promise or async/await syntax.	Explanation: Returned results. For details, see Table 5.

**Table 5** Response
Parameter	Type	Description
CommonMsg	ICommonMsg	Explanation: Common information generated after an API call is complete, including the HTTP status code and error code. For details, see Table 6.
InterfaceResult	Table 7	Explanation: Results outputted for a successful call. For details, see Table 7. Restrictions: This parameter is not included if the value of Status is greater than 300.

**Table 6** ICommonMsg
Parameter	Type	Description
Status	number	Explanation: HTTP status code returned by the OBS server. Value range: A status code is a group of digits indicating the status of a response. It ranges from 2xx (indicating successes) to 4xx or 5xx (indicating errors). For details, see Status Codes.
Code	string	Explanation: Error code returned by the OBS server.
Message	string	Explanation: Error description returned by the OBS server.
HostId	string	Explanation: Request server ID returned by the OBS server.
RequestId	string	Explanation: Request ID returned by the OBS server.
Id2	string	Explanation: Request ID2 returned by the OBS server.
Indicator	string	Explanation: Error code details returned by the OBS server.

**Table 7** AppendObjectOutput
Parameter	Type	Description
RequestId	string	Explanation: Request ID returned by the OBS server
VersionId	string	Explanation: Object version. If versioning is enabled for the bucket, the object version ID will be returned.
ETag	string	Explanation: Base64-encoded, 128-bit MD5 value of an object. It uniquely identifies the content of an object and can be used to check the object integrity. For example, if the ETag is A when an object is uploaded and is B when the object is downloaded, it indicates that the object content has been changed. The ETag reflects changes to the contents of the object, not its metadata. An object created by an upload or copy operation has a unique ETag. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.
NextAppendPosition	int64	Explanation: Position from which the next append upload starts Restrictions: For an object to be appended, the value of position must be set to 0 when the object is uploaded for the first time. For the second append upload, the value of position should be set to the value of NextAppendPosition returned in the response when the first upload is successful. You can also call ObsClient.getObjectMetadata to obtain the value of NextAppendPosition.
SseKms	string	Explanation: SSE-KMS is used for encrypting objects on the server side.
SseKmsKey	string	Explanation: ID of the KMS master key when SSE-KMS is used.
SseC	string	Explanation: SSE-C is used for encrypting objects on the server side.
SseCKeyMd5	string	Explanation: MD5 value of the key used for encrypting objects when SSE-C is used. This value is used to check whether any error occurs during the transmission of the key. Restrictions: Base64-encoded MD5 value of the key, for example, 4XvB3tbNTN+tIEVa0/fGaQ==

Code Examples

You can call ObsClient.appendObject to upload an object and append content to it. This example uses object example/objectname and bucket examplebucket.

    
     
       
       
         // Import the OBS library.
// Use npm to install the client.
const ObsClient = require("esdk-obs-nodejs");
// Use the source code to install the client.
// var ObsClient = require('./lib/obs');

// Create an instance of ObsClient.
const obsClient = new ObsClient({
  // Obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways. Using hard coding may result in leakage.
  // Obtain an AK/SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
  access_key_id: process.env.ACCESS_KEY_ID,
  secret_access_key: process.env.SECRET_ACCESS_KEY,
  // (Optional) If you use a temporary AK/SK pair and a security token to access OBS, you are advised not to use hard coding, which may result in information leakage. You can obtain an AK/SK pair using environment variables or import an AK/SK pair in other ways.
  // security_token: process.env.SECURITY_TOKEN,
  // Enter the endpoint corresponding to the region where the bucket is located. CN-Hong Kong is used here in this example. Replace it with the one currently in use.
  server: "https://obs.ap-southeast-1.myhuaweicloud.com"
});

async function appendObject() {
  try {
    const params = {
      // Specify the bucket name.
      Bucket: "examplebucket",
      // Specify the object (example/objectname in this example).
      Key: "example/objectname",
      // Specify the position where content is appended. For the first upload, set Position to 0. For the subsequent appends, specify the actual position.
      Position: 0,
      // Specify the data stream of the object to upload.
      Body: strings.NewReader("Hello OBS"),
    };
    // Upload the object using the append method.
    const result = await obsClient.appendObject(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Append object(%s) under the bucket(%s) successful!", params.Key, params.Bucket);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      console.log("ETag: %s, NextAppendPosition:%d", result.InterfaceResult.ETag, result.InterfaceResult.NextAppendPosition);
      return;
    };
    console.log("An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    console.log("Status: %d", result.CommonMsg.Status);
    console.log("Code: %s", result.CommonMsg.Code);
    console.log("Message: %s", result.CommonMsg.Message);
    console.log("RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    console.log("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.");
    console.log(error);
  };
};

appendObject();

        

      

    
   