Copying an Object (SDK for Node.js)
If you have any questions during development, post them on the Issues page of GitHub.
Function
This API copies an object stored in OBS to a specified path. 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.
- 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
Parameter |
Type |
Mandatory (Yes/No) |
Description |
---|---|---|---|
Bucket |
string |
Yes |
Explanation: Bucket name Restrictions:
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 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 |
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 |
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:
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 |
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:
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 |
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. |
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). |
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
Type |
Description |
---|---|
NOTE:
This API returns a Promise response, which requires the Promise or async/await syntax. |
Explanation: Returned results. For details, see Table 6. |
Parameter |
Type |
Description |
---|---|---|
CommonMsg |
Explanation: Common information generated after an API call is complete, including the HTTP status code and error code. For details, see Table 7. |
|
InterfaceResult |
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. |
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. |
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 B when the object is downloaded, this indicates the contents of the object have been changed. The ETag reflects changes to an object's contents, not its 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: Simple Copying
Sample code:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 |
// 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/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 names of the source bucket (sourcebucketname in this example) and source object (sourceobjectkey in this example). CopySource: 'sourcebucketname/sourceobjectname' }; // Copy the source 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(); |
Code Examples: Rewriting Object Attributes
Use the Metadata parameter to specify the object's customized metadata to be rewritten and the MetadataDirective parameter to specify the rewrite mode, which can be ObsClient.enums.ReplaceMetadata (rewrite) or ObsClient.enums.CopyMetadata (copy from the source object).
The following sample code shows how to rewrite object properties.
// 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/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 as an 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 names of the source bucket (sourcebucketname in this example) and source object (sourceobjectkey in this example). CopySource: 'sourcebucketname/sourceobjectname' // Specify custom metadata. Metadata: {'property':'property-value'}, // Specify the policy for copying the metadata of the source object. In this example, ObsClient.enums.ReplaceMetadata is used to rewrite the metadata of the source object. MetadataDirective: ObsClient.enums.ReplaceMetadata }; // Copy the 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();
Code Examples: Specifying Copying Conditions
When copying an object, you can specify one or more restriction conditions. If the conditions are met, the object will be copied. Otherwise, an error code will be returned and the copy will fail.
- The ETag of the source object is the MD5 check value of the source object.
- If the object copy request includes CopySourceIfUnmodifiedSince, CopySourceIfMatch, CopySourceIfModifiedSince, or CopySourceIfNoneMatch, and the specified condition is not met, the object copy will fail with error code 412 Precondition Failed returned.
- CopySourceIfModifiedSince and CopySourceIfNoneMatch can be used together. So do CopySourceIfUnmodifiedSince and CopySourceIfMatch.
Sample code:
// 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/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 as an 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 bucket name. Bucket: "examplebucket", // Specify the name of the object copy (example/objectname in this example). Key: 'example/objectname', // Specify the names of the source bucket (sourcebucketname in this example) and source object (sourceobjectkey in this example). CopySource: 'sourcebucketname/sourceobjectname' // Specify the copy conditions. If the source object has been modified since the specified time, it will be copied. CopySourceIfModifiedSince: 'Thu, 31 Dec 2015 16:00:00 GMT', // Specify the copy conditions. If the ETag of the source object is different from the one specified by this parameter, the source object will be copied. CopySourceIfNoneMatch: 'none-match-etag' }; // Copy the 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();
Code Examples: Rewriting an Object ACL
Sample code:
// 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/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 as an 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 bucket name. Bucket: "examplebucket", // Specify the name of the object copy (example/objectname in this example). Key: 'example/objectname', // Specify the names of the source bucket (sourcebucketname in this example) and source object (sourceobjectkey in this example). CopySource: 'sourcebucketname/sourceobjectname' // Rewrite the object ACL to public-read during the copy.. ACL : obsClient.enums.AclPublicRead }; // Copy the 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();
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.