When you download a file (object), you can specify one or more conditions. The file is downloaded only if the specified conditions are met. If the conditions are not met, an error is returned and the download does not start.
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.
Sample code
The following code provides an example of a 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 the 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 region to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
region: 'yourRegion',
authorizationV4: true,
// The temporary AccessKey ID and AccessKey secret obtained from Security Token Service (STS).
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
// The SecurityToken obtained from STS.
stsToken: 'yourSecurityToken',
// Specify the bucket name. For example, examplebucket.
bucket: "examplebucket",
});
const download = document.getElementById('download')
const upload = document.getElementById('upload')
// Upload the file.
upload.addEventListener('click', () => {
// Specify the content of the file to upload.
const file = new Blob(['examplecontent'])
// Specify the full path of the file to upload. For example, exampledir/exampleobject.txt.
const fileName = 'exampledir/exampleobject.txt'
const result = client.put(fileName, file).then(r => console.log(r))
})
// Download the file.
download.addEventListener('click', () => {
// Specify the byte range to download.
const start = 1, end = 5
client.get('exampledir/exampleobject.txt', {
headers: {
// Specify a time in the If-Modified-Since request header. The file is downloaded if the specified time is earlier than the actual modification time of the file. If the specified time is the same as or later than the actual modification time, 304 Not Modified is returned.
"If-Modified-Since": new Date("1970-01-01").toGMTString()
// Specify a time in the If-Unmodified-Since request header. The file is downloaded if the specified time is the same as or later than the actual modification time of the file. If the specified time is earlier than the actual modification time, 412 Precondition Failed is returned.
//"If-Unmodified-Since": new Date(1970-01-01).toGMTString()
// Specify an ETag in the If-Match request header. The file is downloaded if the specified ETag matches the ETag of the file. If the specified ETag does not match, 412 Precondition Failed is returned.
//"If-Match": '5B3C1A2E0563E1B002CC607C****'
// Specify an ETag in the If-None-Match request header. The file is downloaded if the specified ETag does not match the ETag of the file. If the specified ETag matches, 304 Not Modified is returned.
//"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 items to download that meet the conditions')
}
})
})
</script>
</body>
</html>References
For the complete sample code for conditional downloads, see GitHub example.
For more information about the API operation, see GetObject.