You can specify one or more conditions when you download objects. If the specified conditions are met, the object is downloaded. If the specified conditions are not met, an error is returned and the object is not downloaded.

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.
  • OSS SDK for Browser.js is usually used in browsers. To prevent your AccessKey pair from being exposed, we recommend that you use a temporary access credential generated by Security Token Service (STS) to access OSS.

    For more information about how to set up STS, see Use a temporary access credential provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential. For more information, see STS SDK overview. A temporary access credential contains a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret.

Sample code

The following code provides an example on how to perform conditional download:

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

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

<body>
  <button id='upload'>Upload</button>
  <button id='download'>Download</button>
    <!-- import an SDK file -->
  <script type="text/javascript" src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.16.0.min.js"></script>
  <script type="text/javascript">
      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',
         // Specify the temporary AccessKey pair obtained from STS. 
         accessKeyId: 'yourAccessKeyId',
         accessKeySecret: 'yourAccessKeySecret',
         // Specify the security token obtained from STS. 
        stsToken: 'yourSecurityToken',
        // Specify the name of the bucket. Example: examplebucket. 
        bucket: "examplebucket",
      });

    const download = document.getElementById('download')
    const upload = document.getElementById('upload')

    // Upload the object.   
    upload.addEventListener('click', () => {
      // Specify the object to upload. 
      const file = new Blob(['examplecontent'])
      // Specify the full path of the object. Example: exampledir/exampleobject.txt. 
      const fileName = 'exampledir/exampleobject.txt'
      const result = client.put(fileName, file).then(r => console.log(r))
    })

    // Download the object. 
    download.addEventListener('click', () => {
      // Specify the data range of the object to download. 
      const start = 1, end = 5
      client.get('exampledir/exampleobject.txt', {
        headers: {
          // Set the If-Modified-Since header in the request. If the value of this header is earlier than the time when the uploaded object is last modified, the object is downloaded. // If the value of the If-Modified-Since header is equal to or later than the time when the uploaded object is last modified, OSS returns 304 Not Modified. 
          "If-Modified-Since": new Date("1970-01-01").toGMTString()
          // Set the If-Unmodified-Since header in the request. If the value of this header is equal to or later than the time when the uploaded object is last modified, the object is downloaded. If the value of the If-Unmodified-Since header is earlier than the time when the uploaded object is last modified, OSS returns 412 Precondition Failed. 
          //"If-Unmodified-Since": new Date(1970-01-01).toGMTString()
          // Set the If-Match header to an ETag value. If the specified ETag value matches the ETag of the object, the object is downloaded. If the specified ETag value does not match the ETag of the object, OSS returns 412 Precondition Failed. 
          //"If-Match": '5B3C1A2E0563E1B002CC607C****'
          // Set the If-Match header to an ETag value. If the specified ETag value does not match the ETag of the object, the object is downloaded. If the specified ETag value matches the ETag of the object, OSS returns 304 Not Modified. 
          //"If-None-Match": '5B3C1A2E0563E1B002CC607C****'
        },
      }).then(r => {
        if (r.content.length > 0) {                
          const newBlob = new Blob([r.content], { type: r.res.headers['content-type'] });
          const link = document.createElement('a')
          link.href = window.URL.createObjectURL(newBlob)
          link.download = 'foo.txt'
          link.click()
          window.URL.revokeObjectURL(link.href)
        } else {
          console.log ('Error code', r.res.status)
          console.log ('No eligible objects to download')
        }
      })
    })

  </script>
</body>

</html>

References

  • For more information about the complete sample code for conditional download, visit GitHub.
  • For the API operation that is called to perform conditional download, see GetObject.