This topic describes how to copy an object within a bucket or across buckets in the same region.

Usage notes

  • To copy an object, you must have read permissions on the source object and read and write permissions on the destination bucket.
  • The source bucket and the destination bucket must have no retention policies configured. Otherwise, the error message The object you specified is immutable. is returned.
  • The source bucket and the destination bucket must be in the same region. For example, objects in a bucket located in the China (Hangzhou) region cannot be copied to another bucket located in the China (Qingdao) region.

Copy a small object

You can use the copy method to copy objects within the same bucket or between different buckets in the same region. The object size cannot exceed 1 GB.

  • Copy objects within the same bucket

    The following code provides an example on how to copy objects within the same bucket:

    const OSS = require('ali-oss');
    const client = new OSS({
    
      // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access Object Storage Service (OSS) because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the bucket name. Example: examplebucket. 
      bucket: 'examplebucket',
      // Specify whether to enable HTTPS. If you set secure to true, HTTPS is enabled. 
      // secure: true
    })
    // Copy the objects within the same bucket. 
    // Specify the full paths of the source object and the destination object. The full paths of the objects cannot contain the bucket name. 
    client.copy('destexampleobject.txt', 'srcexampleobject.txt',
    // Specify HTTP headers and metadata for the destination object. 
    //{
        // Configure the headers parameter to specify HTTP headers for the destination object. If you do not configure the headers parameter, the HTTP headers of the destination object are the same as the HTTP headers of the source object. The HTTP headers of the source object are copied. 
        // headers:{
            //'Cache-Control': 'no-cache',        
            // If the ETag value of the source object is the same as the ETag value that is specified in the request, OSS copies the object and returns 200 OK. 
            //'if-match': '5B3C1A2E053D763E1B002CC607C5****',
            // If the ETag value of the source object is different from the ETag value that is specified in the request, OSS copies the object and returns 200 OK. 
            //'if-none-match': '5B3C1A2E053D763E1B002CC607C5****', 
            // If the time that is specified in the request is earlier than the time when the object is modified, OSS copies the object and returns 200 OK. 
            //'if-modified-since': '2021-12-09T07:01:56.000Z', 
            // If the time that is specified in the request is later than the time when the object is modified, OSS copies the object and returns 200 OK. 
            //'if-unmodified-since': '2021-12-09T07:01:56.000Z', 
            // Specify the access control list (ACL) of the destination object. In this example, the ACL is set to private, which indicates that only the object owner and authorized users have read and write permissions on the object. 
            //'x-oss-object-acl': 'private', 
            // Specify the tag for the destination object. You can specify multiple tags for the destination object at the same time. 
            //'x-oss-tagging': 'Tag1=1&Tag2=2',
            // Specify whether the CopyObject operation overwrites the object with the same name. If you set x-oss-forbid-overwrite to true, the CopyObject operation cannot overwrite the object with the same name. 
            //'x-oss-forbid-overwrite': 'true', 
        //},
        // Configure the meta parameter to specify metadata for the destination object. If you do not configure the meta parameter, the metadata of the destination object is the same as the metadata of the source object. The metadata of the source object is copied. 
        //meta:{
            // location: 'hangzhou',
            // year: 2015,
            // people: 'mary'
        //}
    //}
    ).then((res) => {
        console.log(res);
    }).catch(e => {
      console.log(e);
    })
  • Copy objects between different buckets in the same region

    The following code provides an example on how to copy objects between two different buckets in the same region:

    const OSS = require('ali-oss');
    const client = new OSS({
    
      // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
      region: 'yourRegion',
      // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
      accessKeyId: 'yourAccessKeyId',
      accessKeySecret: 'yourAccessKeySecret',
      // Specify the name of the destination bucket. 
      bucket: 'destexamplebucket',
    });
    // Specify destobject.txt as the name of the destination object and srcobject.txt as the name of the source object, and specify the bucket in which the source object is stored. 
    client.copy('destobject.txt', 'srcobject.txt', 'srcbucket', {
        // Configure the headers parameter to specify HTTP headers for the destination object. If you do not configure the headers parameter, the HTTP headers of the destination object are the same as the HTTP headers of the source object. The HTTP headers of the source object are copied. 
        // headers:{
        // 'Cache-Control': 'no-cache',
        //},
        // Configure the meta parameter to specify metadata for the destination object. If you do not configure the meta parameter, the metadata of the destination object is the same as the metadata of the source object. The metadata of the source object is copied. 
        // meta:{
        // location: 'hangzhou',
        // year: 2015,
        // people: 'mary'
        //}
      })
      .then(r => console.log(r));

Copy a large object

You can use the multipartUploadCopy method to copy an object whose size is greater than 1 GB in parts.

The following code provides an example on how to copy large objects in parts between two different buckets in the same region:

const OSS = require('ali-oss');
const store = new OSS({
  // Set yourRegion to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourRegion to oss-cn-hangzhou. 
  region: 'yourRegion',
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console. 
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // Specify the name of the destination bucket. 
  bucket: 'destexamplebucket',
});

const copyheaders = {
  // If the ETag value of the source object is the same as the ETag value that is specified in the request, OSS copies the object. Otherwise, OSS returns the HTTP 412 status code (PreconditionFailed). 
  'x-oss-copy-source-if-match': '5B3C1A2E053D763E1B002CC607C5****',
  // If the ETag value of the source object is different from the ETag value that is specified in the request, OSS copies the object and returns 200 OK. Otherwise, OSS returns the HTTP 304 status code (NotModified). 
  'x-oss-copy-source-if-none-match': '5B3C1A2E053D763E1B002CC607C5****', 
  // If the time that is specified in the request is later than or the same as the time when the object is modified, OSS copies the object and returns 200 OK. Otherwise, OSS returns the HTTP 412 status code (PreconditionFailed). 
  'x-oss-copy-source-if-unmodified-since': '2022-12-09T07:01:56.000Z',
  // If the time that is specified in the request is earlier than the time when the object is modified, OSS copies the object and returns 200 OK. Otherwise, OSS returns the HTTP 304 status code (NotModified). 
  'x-oss-copy-source-if-modified-since': '2022-12-09T07:01:56.000Z' 
}
const headers = {
  // Specify the caching behavior of the web page when the object is downloaded. 
  'Cache-Control': 'no-cache',
  //Specify the name of the object when the object is downloaded. 
  'Content-Disposition': 'somename', 
  // Specify the content encoding format of the object when the object is downloaded. 
  'Content-Encoding': 'utf-8',
  // Specify the validity period of the request. Unit: milliseconds. 
  'Expires': '1000'
}

let savedCpt;

// Specify the full path of the destination object. Example: destexampleobject.txt. The path cannot contain the bucket name. 
store.multipartUploadCopy('destexampleobject.txt'
, { 
  // Specify the full path of the source object. Example: srcexampleobject.txt. The path cannot contain the bucket name. 
  sourceKey: 'srcexampleobject.txt',
  // Specify the name of the source bucket. Example: sourcebucket. 
  sourceBucketName: 'sourcebucket'
}).then(r=>console.log(r)).catch(e=>console.log(e))

// Specify the full path of the destination object. Example: destexampleobject.txt. The path cannot contain the bucket name. 
store.multipartUploadCopy('destexampleobject.txt'
, { 
  // Specify the full path of the source object. Example: srcexampleobject.txt. The path cannot contain the bucket name. 
  sourceKey: 'srcexampleobject.txt',
  // Specify the name of the source bucket. Example: sourcebucket. 
  sourceBucketName: 'sourcebucket'
});
  // Specify the maximum number of parts that can be uploaded in parallel. 
  parallel: 4, 
  // Specify the available size for each part. 
  partSize: 1024 * 1024,
  progress: function (p, cpt, res) {
    console.log(p);
    savedCpt = cpt;
    console.log(cpt);
    console.log(res.headers['x-oss-request-id']);
  }, 
  //headers, 
  //copyheaders, 
}).then(r=>console.log(r)).catch(e=>console.log(e))


// Specify the full path of the destination object. Example: destexampleobject.txt. The path cannot contain the bucket name. 
store.multipartUploadCopy('destexampleobject.txt'
, { 
  // Specify the full path of the source object. Example: srcexampleobject.txt. The path cannot contain the bucket name. 
  sourceKey: 'srcexampleobject.txt',
  // Specify the name of the source bucket. Example: sourcebucket. 
  sourceBucketName: 'sourcebucket'
});
  checkpoint: savedCpt,
  progress: function (p, cpt, res) {
    console.log(p);
    console.log(cpt);
    console.log(res.headers['x-oss-request-id']);
  }
});

References

  • Copy a small object
    • For more information about the complete sample code that is used to copy a small object, visit GitHub.
    • For more information about the API operation that you can call to copy a small object, see CopyObject.
  • Copy a large object
    • For more information about the complete sample code that is used to copy a large object, visit GitHub.
    • For more information about the API operation that you can call to copy a large object, see UploadPartCopy.