Prevent objects from being overwritten by objects with the same names - Object Storage Service

By default, if you upload an object that has the same name as an existing object, the existing object is overwritten by the uploaded object. This topic describes how to configure the x-oss-forbid-overwrite request header to prevent existing objects from being overwritten by objects with the same names when you copy objects or perform simple upload or multipart upload.

Usage notes

When you use packaging tools such as Webpack and Browserify, install OSS SDK for Browser.js by running the npm install ali-oss command.
If you want to access an OSS bucket from a browser but no CORS rules are configured for the bucket, the browser rejects the request. Therefore, you must configure CORS rules for a bucket if you want to access the bucket from a browser. For more information, see Installation.
In most cases, OSS SDK for Browser.js is used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use temporary access credentials obtained from Security Token Service (STS) to access OSS.
The temporary access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. For more information about how to obtain temporary access credentials, see Use STS for temporary access authorization.

Prevent overwrites in a simple upload task

The following sample code provides an example on how to prevent objects from being overwritten by objects that have the same names in simple upload:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id="upload">Upload an Object</button>
   <!-- Import the SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
  <script type="text/javascript">
    const client = new OSS({
       // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
       region: 'yourRegion',
       authorizationV4: true,
       // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token that you obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",
      });

    const upload = document.getElementById('upload')

    // Specify the local file that you want to upload. 
    const fileContent = Array(1024 * 1024 * 10).fill('a').join('')
    const fileName = 'example.txt'
    const file = new Blob([fileContent])
    // Specify whether to overwrite an existing object with the same name. In this example, this parameter is set to true, which specifies that the operation does not overwrite an object that has the same name. If an object with the same name exists in the bucket, OSS returns an error. 
    const headers = {
      'x-oss-forbid-overwrite': true
    }
    upload.addEventListener('click', () => {
      // Upload the local file. 
      client.put(fileName, file, { headers }).then(r => console.log(r))
    })

  </script>
</body>

</html>

Prevent overwrites in an object copy task

The following sample code provides an example on how to prevent existing objects from being overwritten by newly copied objects that have the same names:

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <title>Document</title>
</head>

<body>
  <button id="upload">Upload an Object</button>
   <!-- Import the SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"></script>
  <script type="text/javascript">
    const client = new OSS({
       // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
       region: 'yourRegion',
       authorizationV4: true,
       // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
       accessKeyId: 'yourAccessKeyId',
       accessKeySecret: 'yourAccessKeySecret',
       // Specify the security token that you obtained from STS. 
       stsToken: 'yourSecurityToken',
       // Specify the name of the bucket. Example: examplebucket. 
       bucket: "examplebucket",
      });

    const upload = document.getElementById('upload')

    // Specify the object to copy. 
    const fileContent = Array(1024 * 1024 * 5).fill('a').join('')
    const fileName = 'example.txt'
    const file = new Blob([fileContent])
    // Specify whether to overwrite an existing object with the same name. In this example, this parameter is set to true, which specifies that the operation does not overwrite an object that has the same name. If an object with the same name exists in the bucket, OSS returns an error. 
    const headers = {
      'x-oss-forbid-overwrite': true
    }
    upload.addEventListener('click', () => {
      // Copy the object. 
      // Rename the copied object to dest.txt. 
      client.copy("dest.txt",fileName,{headers}).then(r=>console.log(r))
    })

  </script>
</body>

</html>

Prevent overwrites in a multipart upload task

The following code provides an example on how to prevent objects from being overwritten by newly uploaded objects that have the same names in multipart upload:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <button id="upload">Upload an Object</button>
    <!-- Import the SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
        region: 'yourRegion',
        authorizationV4: true,
        // Specify the temporary AccessKey pair obtained from STS. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
        accessKeyId: 'yourAccessKeyId',
        accessKeySecret: 'yourAccessKeySecret',
        // Specify the security token that you obtained from STS. 
        stsToken: 'yourSecurityToken',
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
      });

      const upload = document.getElementById("upload");

      // Specify the object to upload. 
      const fileContent = Array(1024 * 1024 * 5)
        .fill("a")
        .join("");
      const fileName = "src.txt";
      const file = new Blob([fileContent]);
      // Specify whether to overwrite an existing object with the same name. In this example, this parameter is set to true, which specifies that the operation does not overwrite an object that has the same name. If an object with the same name exists in the bucket, OSS returns an error. 
      const headers = {
        "x-oss-forbid-overwrite": true,
      };
      upload.addEventListener("click", () => {
        // Start the multipart upload task. 
        client
          .multipartUpload("dest.txt", file, { headers })
          .then((r) => console.log(r));
      });
    </script>
  </body>
</html>

References

For more information about the API operation that you can call to perform simple upload, see PutObject.
For more information about the API operation that you can call to copy an object, see CopyObject.
The multipartUpload method that is used by OSS SDK for Browser.js to perform multipart upload contains the following three API operations:
- The API operation that you can call to initiate a multipart upload task. For more information, see InitiateMultipartUpload.
- The API operation that you can call to upload data by part. For more information, see UploadPart.
- The API operation that you can call to complete a multipart upload task. For more information, see CompleteMultipartUpload.