repository·master·Indexed 43 days ago
https://github.com/tencentyun/cos-js-sdk-v5Official JavaScript SDK (v1.10.1) for Tencent Cloud Object Storage (COS). It enables web applications to interact with COS buckets for file uploading, downloading, and management using the XML API. Features include support for Client Side Post (CSP) mode, automatic chunked uploading via uploadFile, and secure authentication using temporary credentials (STS) or a getAuthorization callback.
To prevent exposing SecretId and SecretKey in the frontend, do not calculate signatures on the client side. Instead, implement the signature calculation process on your backend server. The frontend should request the signature from your backend via an AJAX call.
When deploying to production, ensure your backend signature service includes your own application's permission/authentication checks.
When using the getAuthorization callback, the SDK provides an options object containing the context of the current request. You must call the callback with either a signature string or an object containing the Authorization field.
options object properties:
Method: The current HTTP request method.Key: The object key (file name) in the bucket.Query: The query parameters object {key: 'val'}.Headers: The request headers object {key: 'val'}.callback return values:
Authorization header value.{ Authorization: '...' }.When implementing custom signature validation or permission logic, you can use the following rules to determine if an operation is allowed based on the pathname, method, and presence of specific query parameters. This is useful for verifying if a request matches specific COS operations like multipart uploads, simple uploads, or permission modifications.
var exist = function (obj, key) {
return obj[key] === undefined;
};To download a file in a browser, first obtain the URL using cos.getObjectUrl. You can then trigger the download using several methods:
response-content-disposition=attachment to the URL to force a download.src of a hidden iframe to the download URL.download attribute: Use an <a> tag with the download attribute (note: compatibility varies in older browsers).Example: Force download via URL parameter
cos.getObjectUrl({
Method: 'PUT',
Key: '1.jpg',
Sign: true
}, function (err, data) {
if (!err) {
// Append parameter to force download
var downloadUrl = data.Url + (data.Url.indexOf('?') > -1 ? '&' : '?') + 'response-content-disposition=attachment';
window.open(downloadUrl);
}
});To perform file uploads using the CSP pattern, initialize the COS instance with a getAuthorization function that fetches signatures from your backend, then use sliceUploadFile for the upload process.
Steps:
cos-js-sdk-v5.min.js script.Bucket and Region.getAuthorization to call your backend endpoint (e.g., a PHP or Node.js script) that returns the signature JSON.cos.sliceUploadFile to handle the upload (this method supports chunked uploading).<input id="file-selector" type="file">
<script src="dist/cos-js-sdk-v5.min.js"></script>
<script>
var Bucket = 'test-1250000000';
var Region = 'ap-guangzhou';
// Initialize instance
var cos = new COS({
CompatibilityMode: true,
ServiceDomain: 'http://cos.default.xxx.com', // Replace with getService domain
Domain: 'http://{Bucket}.cos.{Region}.xxx.com', // Replace with API domain template
getAuthorization: function (options, callback) {
// Request signature from your backend
var url = './auth-json.php?method=' + options.Method + '&path=' + encodeURIComponent('/' + options.Key);
var xhr = new XMLHttpRequest();
xhr.open('GET', url, true);
xhr.onload = function (e) {
callback(e.target.responseText);
};
xhr.send();
},
});
// Listen for file selection
document.getElementById('file-selector').onchange = function () {
var file = this.files[0];
if (!file) return;
// Chunked upload file
cos.sliceUploadFile({
Bucket: Bucket,
Region: Region,
Key: file.name,
Body: file,
}, function (err, data) {
console.log(err, data);
});
};
</script>For projects using webpack or other module bundlers, you can install the SDK as an npm dependency.
npm i cos-js-sdk-v5 --saveBefore using the SDK, ensure the following requirements are met:
Bucket name (format: bucketname-appid) and the Region.SecretId and SecretKey from the API Key Management console.To use the COS JavaScript SDK with Client Side Post (CSP) mode, complete the following prerequisites:
Bucket (bucket name) and Region (region name).SecretId and SecretKey from the console's Key Management section.To run the full demonstration including the STS server:
git clone cos-js-sdk-v5.cd cos-js-sdk-v5 && npm install.server/sts.js or server/sts.php with your secretId, secretKey, bucket, and region. Ensure allowPrefix and allowActions are set correctly.demo/index.html to set the correct Bucket and Region.npm run server.http://127.0.0.1:3000/ in your browser.git clone cos-js-sdk-v5
cd cos-js-sdk-v5
npm install
# ... configure files ...
npm run serverTo begin using the COS JavaScript SDK with Client Side Post (CSP) mode, refer to the Quick Start guide. This guide covers the necessary prerequisites and initial setup steps.
<!-- Refer to ./start.md for the Quick Start guide -->The new COS({}) constructor accepts the following configuration options:
| Parameter | Description | Type | Default |
|---|---|---|---|
SecretId | User's SecretId | String | - |
SecretKey | User's SecretKey (Avoid using in production) | String | - |
FileParallelLimit | Number of concurrent file uploads per instance | Number | 3 |
ChunkParallelLimit | Number of concurrent chunk uploads per file | Number | 3 |
ChunkSize | Size of each chunk in bytes | Number | 1048576 (1MB) |
ProgressInterval | Frequency of onProgress callback in ms | Number | 1000 |
Protocol | Custom request protocol (https: or http:) | String | Matches page protocol |
getAuthorization | Callback to fetch signature (Required if no SecretId/SecretKey provided) | Function | - |
For practical implementation patterns and working code snippets, view the provided HTML example file which demonstrates how to use the SDK in a real-world scenario.
<!-- Refer to ./csp.html for implementation examples -->