Qiniu Cloud SDK for Node.js

The SDK's storage-related APIs support Promise-style asynchronous code. This includes classes such as BucketManager, FormUploader, and ResumeUploader.

While the original Callback-style APIs are still supported, it is highly recommended to switch to the Promise-style API to ensure future compatibility.

Note on Callbacks: If you continue using the Callback style, be aware that errors produced within the callbackFunc will no longer be thrown to the upper layers. You must handle all errors internally within the callbackFunc.

To use CDN-related features (such as URL/directory refreshing, prefetching, or bandwidth monitoring), you must first instantiate a CdnManager using your access key and secret key.

Available CDN features include:

• File refreshing
• Directory refreshing
• File prefetching
• Getting domain traffic/bandwidth
• Getting log download links
• Building timestamp-based anti-leech access links

var accessKey = 'your access key';
var secretKey = 'your secret key';
var mac = new qiniu.auth.digest.Mac(accessKey, secretKey);
var cdnManager = new qiniu.cdn.CdnManager(mac);

To perform resource management operations (stat, move, copy, delete, etc.), you must first instantiate a qiniu.rs.BucketManager using a Mac object for authentication and a qiniu.conf.Config object for configuration.

const mac = new qiniu.auth.digest.Mac(accessKey, secretKey);
const config = new qiniu.conf.Config();
config.useHttpsDomain = true;
const bucketManager = new qiniu.rs.BucketManager(mac, config);

The recommended way to install the Qiniu Cloud SDK for Node.js is via npm.

$ npm install qiniu

All functions in the Qiniu Node.js SDK require valid authorization. You must use a pair of Access Key and Secret Key associated with your Qiniu account to sign requests.

To obtain your keys:

1. Register a Qiniu developer account.
2. Log in to the Qiniu developer console and navigate to the key management section to view your Access Key and Secret Key.

If you cannot use npm, you can obtain the SDK through the following methods:

1. Release Versions: Download stable, versioned releases from the GitHub releases page. These versions are stable and include a CHANGELOG.
2. Git Repository: You can git clone the source code directly. Note that code in non-master branches may change frequently and should be used with caution.

For server-side direct uploads, you must first create a qiniu.conf.Config object. This object defines the storage region and other upload parameters.

While the zone property is deprecated, it is still supported for compatibility. It is recommended to use regionsProvider instead, which is set via qiniu.httpc.Region.fromRegionId(regionId).

const config = new qiniu.conf.Config();
// Specify the region using a Region ID (e.g., 'z0' for East China-Zhejiang)
config.regionsProvider = qiniu.httpc.Region.fromRegionId('z0');

When clients (Web or Mobile) upload files, they must obtain an upload token from your business server. This token is generated using the Node.js SDK and then distributed to the client.

To generate any token, you must first create a mac authentication object using your AccessKey and SecretKey.

const accessKey = 'your access key';
const secretKey = 'your secret key';
const mac = new qiniu.auth.digest.Mac(accessKey, secretKey);

By default, Qiniu returns a JSON containing hash and key. You can customize this response using the returnBody parameter in PutPolicy. You can use magic variables (like $(key), $(etag), $(fsize)) and custom variables (prefixed with x:) to define the JSON structure.

const options = {
  scope: bucket,
  returnBody: '{"key":"$(key)","hash":"$(etag)","fsize":$(fsize),"bucket":"$(bucket)","name":"$(x:name)"}'
};
const putPolicy = new qiniu.rs.PutPolicy(options);
const uploadToken = putPolicy.uploadToken(mac);