Copying an Object Version (SDK for Node.js)_Object Storage Service

Function

This API copies an object version in a specified bucket. You can copy an object of up to 5 GB in a single operation.

Restrictions

To copy 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.
This API requires carrying the information about the source bucket and object using headers. A message body cannot be carried.
The target object size ranges from 0 to 5 GB. If the source object size exceeds 5 GB, you must use a multipart copying API by referring to Copying a Part (SDK for Node.js).

Method

ObsClient.copyObject(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.
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.eu-west-101.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
CopySource	string	Yes	Explanation: Names of the source bucket and object. If the source object has multiple versions, the versionId parameter is used to specify the desired version. Example: source_bucket/sourceObject?versionId=G001117FCE89978B0000401205D5DC9A Restrictions: None Restrictions: Full-width characters and percent signs (%) must be URL-encoded. Default value: None
ACL	AclType	No	Explanation: ACL that can be pre-defined during the object copy. For details about the ACL, see ACLs. Restrictions: None Value range: See Table 2. Default value: None
MetadataDirective	MetadataDirectiveType	No	Explanation: Policy for copying the source object's attributes Restrictions: None Value range: See Table 3. Default value: None
CopySourceIfMatch	string	No	Explanation: If the ETag of the source object is the same as the one specified by this parameter, it is copied. Otherwise, an error is returned. Restrictions: None Value range: The value must contain 32 characters. Default value: None
CopySourceIfNoneMatch	string	No	Explanation: If the ETag of the source object is different from the one specified by this parameter, it is copied. Otherwise, an error is returned. Restrictions: None Value range: The value must contain 32 characters. Default value: None
CopySourceIfUnmodifiedSince	string	No	Explanation: If the source object has not been modified since the specified time, it is copied. Otherwise, an exception is thrown. Restrictions: The value must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt. Value range: None Default value: None
CopySourceIfModifiedSince	string	No	Explanation: If the source object has been modified since the specified time, it is copied. Otherwise, an exception is thrown. Restrictions: The value must conform with the HTTP time format specified in http://www.ietf.org/rfc/rfc2616.txt. Value range: None 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: 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
CopySourceSseC	string	Yes when SSE-C is used	Explanation: SSE-C is used for encrypting objects on the server side. Restrictions: Only AES256 is supported. Value range: AES256 Default value: None
CopySourceSseCKey	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= Value range: None Default value: None
CacheControl	string	No	Explanation: Cache-Control in the response is rewritten. Restrictions: None Value range: See the Cache-Control values defined in HTTP. Default value: None
ContentDisposition	string	No	Explanation: Content-Disposition in the response is rewritten. Restrictions: None Value range: See the Content-Disposition values defined in HTTP. Default value: None
ContentEncoding	string	No	Explanation: Content-Encoding in the response is rewritten. Restrictions: None Value range: See the Content-Encoding values defined in HTTP. Default value: None
ContentLanguage	string	No	Explanation: Content-Language in the response is rewritten. Restrictions: None Value range: See the Content-Language values defined in HTTP. Default value: None
ContentType	string	No	Explanation: Content-Type in the response is rewritten. Restrictions: None Value range: See What Is Content-Type (MIME)? (SDK for Node.js) Default value: None
Expires	string	No	Explanation: Expires in the response is rewritten. Restrictions: None Value range: See the Expires values defined in HTTP. Default value: None
StorageClass	StorageClassType	No	Explanation: Storage class configured when copying the object. Restrictions: None Value range: See Table 4. Default value: None. If this parameter is not specified, the storage class of the bucket is used as that of the object.
Metadata	object	No	Explanation: Custom metadata of the target object. 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: 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 object to copy 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 object to copy. 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 object to copy. 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 object to copy, 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
SuccessActionRedirect	string	No	Explanation: Address (URL) to which a successfully answered request is redirected. If the value is valid and the request is successful, OBS returns status code 303. Location contains the value of this parameter, as well as the bucket name, object name, and object ETag. If the value is invalid, OBS ignores this parameter. In such case, the Location header is the object address, and OBS returns a status code based on whether the operation succeeded or failed. Restrictions: None Value range: None 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** MetadataDirectiveType
Constant	Default Value	Description
ObsClient.enums.CopyMetadata	COPY	When copying an object, the object's attributes are also copied. NOTICE: This value is used only in the API for Copying an Object (SDK for Node.js).
ObsClient.enums.ReplaceMetadata	REPLACE	REPLACE uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified.
ObsClient.enums.ReplaceNewMetadata	REPLACE_NEW	REPLACE_NEW replaces the metadata that already has a value, assigns a value to the metadata that does not have a value, and retains the metadata that is not specified. NOTICE: This value is used only in the API for Configuring Object Metadata (SDK for Node.js).

**Table 4** 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.

If CopySourceIfUnmodifiedSince, CopySourceIfMatch, CopySourceIfModifiedSince, or CopySourceIfNoneMatch is included but the specified condition is not met, 412 precondition failed will be returned.
CopySourceIfModifiedSince and CopySourceIfNoneMatch can be used together. So can CopySourceIfUnmodifiedSince and CopySourceIfMatch.

Responses

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

**Table 6** 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 7.
InterfaceResult	Table 8	Explanation: Results outputted for a successful call. For details, see Table 8. Restrictions: This parameter is not included if the value of Status is greater than 300.

**Table 7** 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 8** CopyObjectOutput
Parameter	Type	Description
RequestId	string	Explanation: Request ID returned by the OBS server.
LastModified	string	Explanation: Time when the target object was last modified, in UTC.
ETag	string	Explanation: Base64-encoded, 128-bit MD5 value of the target object. The ETag is a unique identifier for the object's contents, used to determine if the object has been updated. For example, if the ETag value is A when an object is uploaded and becomes B when the object is downloaded, this indicates the contents of the object were changed. The ETag reflects changes of an object, not of the metadata. Objects created by the upload and copy operations have unique ETags after being encrypted using MD5. Restrictions: If an object is encrypted using server-side encryption, the ETag is not the MD5 value of the object.
CopySourceVersionId	string	Explanation: Version ID of the source object.
VersionId	string	Explanation: Version ID of the target object.

Code Examples

You can call ObsClient.copyObject to copy a specific version of an object by specifying versionId in the CopySource parameter. Sample code is as follows:

    
     
       
       
         // 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 ObsClient instance.
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/eu/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. EU-Dublin is used here in this example. Replace it with the one currently in use.
  server: "https://obs.eu-west-101.myhuaweicloud.eu"
});

async function copyObject() {
  try {
    const params = {
      // Specify the target bucket name.
      Bucket: "examplebucket",
      // Specify the name of the object copy (example/objectname in this example).
      Key: 'example/objectname',
      // Specify the source bucket name (sourcebucketname in this example), source object name (sourceobjectkey in this example), and source object version ID (G001117FCE89978B0000401205D5DC9A in this example).
      CopySource: 'sourcebucketname/sourceobjectname?versionId=G001117FCE89978B0000401205D5DC9A'
    };
    // Copy a version of an object.
    const result = await obsClient.copyObject(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Copy Object(bucket:%s, object: %s) successful from bucket/object: %s!", params.Bucket, params.Key, params.CopySource);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      console.log("ETag: %s, LastModified:%s", result.InterfaceResult.ETag, result.InterfaceResult.LastModified);
      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);
  };
};

copyObject();

        

      

    
   

Copying an Object Version (SDK for Node.js)

Function

Restrictions

Method

Request Parameters

Responses

Code Examples

Feedback

Was this page helpful?