Node.js SDK provides APIs for getting object URLs and pre-signed request URLs. For details, see the descriptions and samples below.
Note:
- You are advised to use a temporary key to generate a pre-signed URL for the security of your requests such as uploads and downloads. When you apply for a temporary key, follow the Principle of Least Privilege to avoid leaking resources besides your buckets and objects.
- If you need to use a permanent key to generate a pre-signed URL, you are advised to limit the permission of the permanent key to uploads and downloads only to avoid risks.
In all COS XML API requests, the authentication credential Authorization
is required for all operations on private resources for COS to determine whether a request is valid.
There are two ways to use the authentication credential:
The COS.getAuthorization
method is used to calculate the authentication credential (Authorization), which is the signing information used to verify the validity of the request.
Note:It is recommended that this method is only used for frontend debugging but not in actual projects, as it may disclose keys.
Obtaining the authentication credential for file download:
// Log in to the [CAM console](https://console.intl.cloud.tencent.com/cam/capi) to check and manage the `SecretId` and `SecretKey` of your project.
var COS = require('cos-nodejs-sdk-v5');
var Authorization = COS.getAuthorization({
SecretId: 'SECRETID',
SecretKey: 'SECRETKEY',
Method: 'get',
Key: 'a.jpg',
Expires: 60,
Query: {},
Headers: {}
});
Parameter | Description | Type | Required |
---|---|---|---|
SecretId | User SecretId | String | Yes |
SecretKey | User's SecretKey |
String | Yes |
Method | HTTP request method such as GET , POST , DELETE , or HEAD |
String | Yes |
Key | Object key (object name) is the unique ID of an object in a bucket. If the request operation is to be performed on a file, this parameter is required and should be a filename. If the operation is on a bucket, this parameter should be left empty. | String | No |
Query | Request parameters to include in the signature. Format: {key: 'val'} | Object | No |
Headers | Request headers to include in the signature. Format: {key: 'val'} | Object | No |
Expires | Signature expiration time in seconds. Default value: 900 |
Number | No |
The returned value is the calculated authentication credential string authorization
.
Sample 1. Get an unsigned object URL
var url = cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Sign: false
});
Sample 2. Get a signed object URL
var url = cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
});
Sample 3. If the signing process is asynchronous, you need to get the signed URL through a callback
cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Sign: false
}, function (err, data) {
console.log(err || data.Url);
});
Sample 4. Specify the validity period of a link
cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Sign: true,
Expires: 3600, // Unit: second
}, function (err, data) {
console.log(err || data.Url);
});
Sample 5. Get the file URL and download the file
var request = require('request');
var fs = require('fs');
cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Sign: true
}, function (err, data) {
if (err) return console.log(err);
console.log(data.Url);
var req = request(data.Url, function (err, response, body) {
console.log(err || body);
});
var writeStream = fs.createWriteStream(__dirname + '/1.jpg');
req.pipe(writeStream);
});
Sample 6. Generate the pre-signed URL with the signature containing Query
and Header
cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Sign: true,
/* The HTTP request parameters passed in should be the same as those of the actual request. This can prevent users from tampering with the HTTP request parameters. */
Query: {
'imageMogr2/thumbnail/200x/': ''
},
/* The HTTP request headers passed in should be included in the actual request. This can prevent users from tampering with the HTTP request headers that are signed here. */
Headers: {
host: 'xxx' /* Specified host for access. Error code 403 will be reported for access by a non-specified host. */
},
}, function (err, data) {
console.log(err || data.Url);
});
Sample 1. Get a pre-signed URL for Put Object
upload
var request = require('request');
var fs = require('fs');
cos.getObjectUrl({
Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
Region: 'COS_REGION', /* Bucket region, such as `ap-beijing`. Required. */
Key: '1.jpg', /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
Method: 'PUT',
Sign: true
}, function (err, data) {
if (err) return console.log(err);
console.log(data.Url);
var readStream = fs.createReadStream(__dirname + '/1.jpg');
var req = request({
method: 'PUT',
url: data.Url,
}, function (err, response, body) {
console.log(err || body);
});
readStream.pipe(req);
});
Parameter | Description | Type | Required |
---|---|---|---|
Bucket | Bucket name in the format of BucketName-APPID . |
String | Yes |
Region | Bucket region. For the enumerated values, please see Regions and Access Endpoints. | String | Yes |
Key | Object key (object name) is the unique ID of an object in a bucket. If the request operation is to be performed on a file, this parameter is required and should be a filename. If the operation is on a bucket, this parameter should be left empty | String | Yes |
Sign | Whether to return a signed URL. Default value: true |
Boolean | No |
Protocol | It can be http: (default) or https: |
String | No |
Domain | Bucket access domain. Default value: {BucketName-APPID}.cos.{Region}.myqcloud.com |
String | No |
Method | HTTP request method such as GET , POST , DELETE , or HEAD . Default value: GET |
String | No |
Query | Request parameters to include in the signature. Format: {key: 'val'} | Object | No |
Headers | Request headers to include in the signature. Format: {key: 'val'} | Object | No |
Expires | Signature expiration time in seconds. Default value: 900 |
Number | No |
A string is returned in one of the two ways:
function(err, data) { ... }
Parameter | Description | Type |
---|---|---|
err | Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. | Object |
data | Content returned when the request is successful. If the request fails, this parameter is empty. | Object |
- Url | Calculated URL | String |
Was this page helpful?