aliyun OSS(object storage service) Node.js client.
npm install ali-oss --save
Node.js >= 8.0.0 required. You can use 4.x in Node.js < 8.
OSS, Object Storage Service. Equal to well known Amazon S3.
| region | country | city | endpoint | internal endpoint |
|---|---|---|---|---|
| oss-cn-hangzhou | China | HangZhou | oss-cn-hangzhou.aliyuncs.com | oss-cn-hangzhou-internal.aliyuncs.com |
| oss-cn-shanghai | China | ShangHai | oss-cn-shanghai.aliyuncs.com | oss-cn-shanghai-internal.aliyuncs.com |
| oss-cn-qingdao | China | QingDao | oss-cn-qingdao.aliyuncs.com | oss-cn-qingdao-internal.aliyuncs.com |
| oss-cn-beijing | China | BeiJing | oss-cn-beijing.aliyuncs.com | oss-cn-beijing-internal.aliyuncs.com |
| oss-cn-shenzhen | China | ShenZhen | oss-cn-shenzhen.aliyuncs.com | oss-cn-shenzhen-internal.aliyuncs.com |
| oss-cn-hongkong | China | HongKong | oss-cn-hongkong.aliyuncs.com | oss-cn-hongkong-internal.aliyuncs.com |
| oss-us-west-1 | US | Silicon Valley | oss-us-west-1.aliyuncs.com | oss-us-west-1-internal.aliyuncs.com |
| oss-ap-southeast-1 | Singapore | Singapore | oss-ap-southeast-1.aliyuncs.com | oss-ap-southeast-1-internal.aliyuncs.com |
Go to OSS website, create a new account for new user.
After account created, you can create the OSS instance and get the accessKeyId and accessKeySecret.
Each OSS instance required accessKeyId, accessKeySecret and bucket.
Create a Bucket store instance.
options:
putBucket() create one first.region.oss-cn-hangzhou.false.
If your servers are running on aliyun too, you can set true to save lot of money.60sexample:
var oss = require('ali-oss');
var store = oss({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
region: 'oss-cn-hangzhou'
});
List buckets in this account.
parameters:
null
prefix keymarker, including marker key100, limit to 1000Success will return buckets list on buckets properties.
BucketMeta will contains blow properties:
oss-cn-hangzhou-a2015-02-19T08:39:44.000Zid and displayNameexample:
var result = yield store.listBuckets({
"max-keys": 10
});
console.log(result);
Create a new bucket.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhen
If change exists bucket region, will throw BucketAlreadyExistsError.
If region value invalid, will throw InvalidLocationConstraintError.Success will return the bucket name on bucket properties.
example:
helloworld location on HongKongyield store.putBucket('helloworld', 'oss-cn-hongkong');
// use it by default
store.useBucket('helloworld', 'oss-cn-hongkong');
helloworld location on HongKong StorageClass Archiveyield store.putBucket('helloworld', 'oss-cn-hongkong', { StorageClass: 'Archive' });
// use it by default
store.useBucket('helloworld', 'oss-cn-hongkong');
Delete an empty bucket.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
example:
yield store.deleteBucket('helloworld', {
region: 'oss-cn-hongkong'
});
Use the bucket.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenexample:
helloworld as the default bucketstore.useBucket('helloworld', 'oss-cn-hongkong');
Get bucket information,include CreationDate、ExtranetEndpoint、IntranetEndpoint、Location、Name、StorageClass、 Owner、AccessControlList
parameters:
example:
helloworld as the default bucketstore.getBucketInfo('helloworld').then( (res) => {
console.log(res.bucket)
})
Get bucket location
parameters:
example:
helloworld as the default bucketstore.getBucketLocation('helloworld').then( (res) => {
console.log(res.location)
})
Update the bucket ACL.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenpublic-read-write, public-read and privateSuccess will return:
example:
helloworld to public-read-writeyield store.putBucketACL('helloworld', 'oss-cn-hongkong', 'public-read-write');
Get the bucket ACL.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
example:
helloworldvar result = yield store.getBucketACL('helloworld', 'oss-cn-hongkong');
console.log(result.acl);
Update the bucket logging settings.
Log file will create every one hour and name format: <prefix><bucket>-YYYY-mm-DD-HH-MM-SS-UniqueString.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
example:
helloworld logging and save with prefix logs/yield store.putBucketLogging('helloworld', 'oss-cn-hongkong', 'logs/');
Get the bucket logging settings.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
nullexample:
helloworld logging settingsvar result = yield store.getBucketLogging('helloworld', 'oss-cn-hongkong');
console.log(result.enable, result.prefix);
Delete the bucket logging settings.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Set the bucket as a static website.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenindex.htmlSuccess will return:
example:
yield store.putBucketWebsite('hello', 'oss-cn-hangzhou', {
index: 'index.html'
});
Get the bucket website config.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
nullDelete the bucket website config.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Set the bucket request Referer white list.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenReferer white list, e.g.:
[
'https://npm.taobao.org',
'http://cnpmjs.org'
]
Success will return:
example:
yield store.putBucketReferer('hello', 'oss-cn-hangzhou', false, [
'https://npm.taobao.org',
'http://cnpmjs.org'
]);
Get the bucket request Referer white list.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Referer white listDelete the bucket request Referer white list.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Set the bucket object lifecycle.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenRule will contains blow properties:
Enabled or Disableddays2022-10-11T00:00:00.000Z
date and days only set one.Success will return:
example:
yield store.putBucketLifecycle('hello', 'oss-cn-hangzhou', [
{
id: 'delete after one day',
prefix: 'logs/',
status: 'Enabled',
days: 1
},
{
prefix: 'logs2/',
status: 'Disabled',
date: '2022-10-11T00:00:00.000Z'
}
]);
Get the bucket object lifecycle.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Delete the bucket object lifecycle.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Set CORS rules of the bucket object
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenRule will contains below properties:
Success will return:
example:
yield store.putBucketCORS('hello', 'oss-cn-hangzhou', [
{
allowedOrigin: '*',
allowedMethod: [
'GET',
'HEAD',
],
}
]);
Get CORS rules of the bucket object.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
Delete CORS rules of the bucket object.
parameters:
oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenSuccess will return:
All operations function is generator, except signatureUrl.
generator function format: functionName*(...).
Add an object to the bucket.
parameters:
Content-Type entity headerx-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 } var customValue = {var1: 'value1', var2: 'value2'}
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000Success will return the object information.
object:
example:
var filepath = '/home/ossdemo/demo.txt';
var object = yield store.put('ossdemo/demo.txt', filepath);
console.log(object);
{
name: 'ossdemo/demo.txt',
res: {
status: 200,
headers: {
date: 'Tue, 17 Feb 2015 13:28:17 GMT',
'content-length': '0',
connection: 'close',
etag: '"BF7A03DA01440845BC5D487B369BC168"',
server: 'AliyunOSS',
'x-oss-request-id': '54E341F1707AA0275E829244'
},
size: 0,
rt: 92
}
}
var object = yield store.put('ossdemo/buffer', new Buffer('foo content'));
console.log(object);
{
name: 'ossdemo/buffer',
url: 'http://demo.oss-cn-hangzhou.aliyuncs.com/ossdemo/buffer',
res: {
status: 200,
headers: {
date: 'Tue, 17 Feb 2015 13:28:17 GMT',
'content-length': '0',
connection: 'close',
etag: '"xxx"',
server: 'AliyunOSS',
'x-oss-request-id': '54E341F1707AA0275E829243'
},
size: 0,
rt: 92
}
}
var filepath = '/home/ossdemo/demo.txt';
var object = yield store.put('ossdemo/readstream.txt', fs.createReadStream(filepath));
console.log(object);
{
name: 'ossdemo/readstream.txt',
url: 'http://demo.oss-cn-hangzhou.aliyuncs.com/ossdemo/readstream.txt',
res: {
status: 200,
headers: {
date: 'Tue, 17 Feb 2015 13:28:17 GMT',
'content-length': '0',
connection: 'close',
etag: '"BF7A03DA01440845BC5D487B369BC168"',
server: 'AliyunOSS',
'x-oss-request-id': '54E341F1707AA0275E829242'
},
size: 0,
rt: 92
}
}
Add a stream object to the bucket.
parameters:
chunked encoding will be used if absentContent-Type entity headerx-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 } var customValue = {var1: 'value1', var2: 'value2'}
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000Success will return the object information.
object:
example:
var filepath = '/home/ossdemo/demo.txt';
var object = yield store.putStream('ossdemo/readstream.txt', fs.createReadStream(filepath));
console.log(object);
{
name: 'ossdemo/readstream.txt',
url: 'http://demo.oss-cn-hangzhou.aliyuncs.com/ossdemo/readstream.txt',
res: {
status: 200,
headers: {
date: 'Tue, 17 Feb 2015 13:28:17 GMT',
'content-length': '0',
connection: 'close',
etag: '"BF7A03DA01440845BC5D487B369BC168"',
server: 'AliyunOSS',
'x-oss-request-id': '54E341F1707AA0275E829242'
},
size: 0,
rt: 92
}
}
Append an object to the bucket, it's almost same as put, but it can add content to existing object rather than override it.
All parameters are same as put except for options.position
Content-Type entity headerx-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000object:
example:
var object = yield store.apend('ossdemo/buffer', new Buffer('foo'));
// append content to the existing object
object = yield store.apend('ossdemo/buffer', new Buffer('bar'), {
position: object.nextAppendPosition,
});
Get the Object url.
If provide baseUrl, will use baseUrl instead the default endpoint.
e.g.:
const cdnUrl = client.getObjectUrl('foo/bar.jpg', 'https://mycdn.domian.com');
// cdnUrl should be `https://mycdn.domian.com/foo/bar.jpg`
Get the Object url.
If provide baseUrl, will use baseUrl instead the default bucket and endpoint .
Suggest use generateObjectUrl instead of getObjectUrl.
e.g.:
const url = client.generateObjectUrl('foo/bar.jpg');
// cdnUrl should be `https://${bucketname}.${endpotint}foo/bar.jpg`
const cdnUrl = client.generateObjectUrl('foo/bar.jpg', 'https://mycdn.domian.com');
// cdnUrl should be `https://mycdn.domian.com/foo/bar.jpg`
Head an object and get the meta info.
parameters:
Success will return the object's meta information.
object:
put(), will return null.
If return status 304, meta will be null tooexample:
yield this.store.put('ossdemo/head-meta', new Buffer('foo'), {
meta: {
uid: 1,
path: 'foo/demo.txt'
}
});
var object = this.store.head('ossdemo/head-meta');
console.log(object);
{
status: 200,
meta: {
uid: '1',
path: 'foo/demo.txt'
},
res: { ... }
}
var object = this.store.head('ossdemo/head-meta');
// will throw NoSuchKeyError
Get an object from the bucket.
parameters:
file is null or ignore this parameter, function will return info contains content property.x-oss-process
e.g.: {process: 'image/resize,w_200'}Range: bytes=0-9Success will return the info contains response.
object:
file parameter is null or ignoreIf object not exists, will throw NoSuchKeyError.
example:
var filepath = '/home/ossdemo/demo.txt';
yield store.get('ossdemo/demo.txt', filepath);
_ Store object to a writestream
yield store.get('ossdemo/demo.txt', somestream);
var result = yield store.get('ossdemo/demo.txt');
console.log(Buffer.isBuffer(result.content));
var filepath = '/home/ossdemo/demo.png';
yield store.get('ossdemo/demo.png', filepath, {process: 'image/resize,w_200'});
var filepath = '/home/ossdemo/demo.txt';
yield store.get('ossdemo/not-exists-demo.txt', filepath);
// will throw NoSuchKeyError
Get an object read stream.
parameters:
x-oss-processSuccess will return the stream instance and response info.
object:
null.If object not exists, will throw NoSuchKeyError.
example:
var result = yield store.getStream('ossdemo/demo.txt');
result.stream.pipe(fs.createWriteStream('some file.txt'));
Delete an object from the bucket.
parameters:
Success will return the info contains response.
object:
If delete object not exists, will also delete success.
example:
yield store.delete('ossdemo/someobject');
yield store.delete('ossdemo/some-not-exists-object');
Copy an object from sourceName to name.
parameters:
sourceName start with /, meaning it's a full name contains the bucket name.
e.g.: /otherbucket/logo.png meaning copy otherbucket logn.png object to current bucket.x-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }
If the meta set, will override the source object meta.Success will return the copy result in data property.
object:
", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"If source object not exists, will throw NoSuchKeyError.
example:
var result = yield store.copy('newName', 'oldName');
var result = yield store.copy('logo.png', '/other-bucket/logo.png');
Set an exists object meta.
parameters:
x-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }
If meta: null, will clean up the exists metaSuccess will return the copy result in data property.
2015-02-19T08:39:44.000Z", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"If object not exists, will throw NoSuchKeyError.
example:
var result = yield store.putMeta('ossdemo.txt', {
uid: 1, pid: 'p123'
});
console.log(result);
yield store.putMeta('ossdemo.txt', null);
Delete multi objects in one request.
parameters:
false, verbose mode
quiet mode: if all objects delete succes, return emtpy response.
otherwise return delete error object results.
verbose mode: return all object delete results.Success will return delete success objects in deleted property.
example:
var result = yield store.deleteMulti(['obj1', 'obj2', 'obj3'], {
quiet: true
});
var result = yield store.deleteMulti(['obj1', 'obj2', 'obj3']);
List objects in the bucket.
parameters:
null
prefix keymarker, including marker key/ only search current dir, not including subdir100, limit to 1000Success will return objects list on objects properties.
ObjectMeta will contains blow properties:
2015-02-19T08:39:44.000Z", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"Normal344606Standardid and displayNameexample:
var result = yield store.list();
console.log(result.objects);
fun/ dir including subdirs objectsvar result = yield store.list({
prefix: 'fun/'
});
console.log(result.objects);
fun/ dir objects, not including subdirsvar result = yield store.list({
prefix: 'fun/',
delimiter: '/'
});
console.log(result.objects);
Create a signature url for download or upload object.
parameters:
1800x-oss-process
e.g.: {process: 'image/resize,w_200'}Success will return signature url.
example:
var url = store.signatureUrl('ossdemo.txt');
console.log(url);
var url = store.signatureUrl('ossdemo.txt', {
expires: 3600,
method: 'PUT'
});
console.log(url);
var url = store.signatureUrl('ossdemo.txt', {
expires: 3600,
response: {
'content-type': 'text/custom',
'content-disposition': 'attachment'
}
});
console.log(url);
var url = store.signatureUrl('ossdemo.png', {
process: 'image/resize,w_200'
});
console.log(url);
var url = store.signatureUrl('ossdemo.png', {
expires: 3600,
process: 'image/resize,w_200'
});
console.log(url);
Set object's ACL.
parameters:
Success will return:
example:
yield store.putACL('ossdemo.txt', 'public-read');
Get object's ACL.
parameters:
Success will return:
example:
var result = yield store.getACL('ossdemo.txt');
console.log(result.acl);
Restore Object.
parameters:
Success will return:
example:
var result = yield store.restore('ossdemo.txt');
console.log(result.status);
Before transmitting data in the Multipart Upload mode, you must call the Initiate Multipart Upload interface to notify the OSS to initiate a Multipart Upload event. The Initiate Multipart Upload interface returns a globally unique Upload ID created by the OSS server to identify this Multipart Upload event.
parameters:
x-oss-meta- prefix stringCache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000x-oss-server-side-encryption: AES256Success will return:
example:
var result = yield store.initMultipartUpload('object');
console.log(result);
After initiating a Multipart Upload event, you can upload data in parts based on the specified object name and Upload ID.
parameters:
Success will return:
example:
var name = 'object';
var result = yield store.initMultipartUpload(name);
var uploadId = result.uploadId;
var file; //the data you want to upload, is a File or FileName(only in node)
//if file part is 10
var partSize = 100 * 1024;
var fileSize = 10 * partSize;//you need to calculate
var dones = [];
for (var i = 1; i <= 10; i++) {
var start = partSize * (i -1);
var end = Math.min(start + partSize, fileSize);
var part = yield store.uploadPart(name, uploadId, i, file, start, end);
dones.push({
number: i,
etag: part.etag
});
console.log(part);
}
//end need to call completeMultipartUpload api
Using Upload Part Copy, you can copy data from an existing object and upload a part of the data. When copying a file larger than 1 GB, you must use the Upload Part Copy method. If you want to copy a file smaller than 1 GB, see Copy Object.
parameters:
0-102400Success will return:
example:
var name = 'object';
var result = yield store.initMultipartUpload(name);
var partSize = 100 * 1024;//100kb
//if file part is 10
for (var i = 1; i <= 10; i++) {
var start = partSize * (i -1);
var end = Math.min(start + partSize, fileSize);
var range = start + '-' + (end - 1);
var part = yield store.uploadPartCopy(name, result.uploadId, i, range, {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
});
console.log(part);
}
//end need complete api
After uploading all data parts, you must call the Complete Multipart Upload API to complete Multipart Upload for the entire file.
parameters:
var customValue = {var1: 'value1', var2: 'value2'}
Success will return:
example:
//init multipart
var name = 'object';
var result = yield store.initMultipartUpload(name);
//upload part
var file; //the data you want to upload, this example size is 10 * 100 * 1024
var fileSize;//you need to calculate
var partSize = 100 * 1024;//100kb
var done = [];
//if file part is 10
for (var i = 1; i <= 10; i++) {
var start = partSize * (i -1);
var end = Math.min(start + partSize, fileSize);
var data = file.slice(start, end);
var part = yield store.uploadPart(name, result.uploadId, i, data);
console.log(part);
done.push({
number: i,
etag: part.res.headers.etag
});
}
//complete
var completeData = yield store.completeMultipartUpload(name, result.uploadId, done);
console.log(completeData);
Upload file with OSS multipart.
this function contains initMultipartUpload, uploadPart, completeMultipartUpload.
parameters:
x-oss-meta- prefix stringContent-Type entity header var customValue = {var1: 'value1', var2: 'value2'}
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000Success will return:
example:
var result = yield store.multipartUpload('object', '/tmp/file');
console.log(result);
var result = yield store.multipartUpload('object', '/tmp/file', {
parallel: 4,
partSize: 1024 * 1024,
progress: function* (p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
var result = yield store.multipartUpload('object', '/tmp/file', {
checkpoint: savedCpt,
progress: function* (p, cpt, res) { //progress is generator
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
//thunk
function thunkProgress(p, cpt, res) {
return function(done) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
done();
}
}
var result1 = yield store.multipartUpload('object', '/tmp/file', {
progress: thunkProgress
});
//generator
function* generatorProgress(p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
var result2 = yield store.multipartUpload('object', '/tmp/file', {
progress: generatorProgress
});
tips: cancel multipartUpload, now only support browser.
//start upload
try {
var result = yield store.multipartUpload('object', '/tmp/file', {
checkpoint: savedCpt,
progress: function* (p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
} catch (err) {
//if cancel will catch cancel event
if (store.isCancel()) {
//do something
}
}
//the other event to cancel, for example: click event
//to cancel upload must use the same client instance
store.cancel();
Copy file with OSS multipart.
this function contains head, initMultipartUpload, uploadPartCopy, completeMultipartUpload.
When copying a file larger than 1 GB, you should use the Upload Part Copy method. If you want to copy a file smaller than 1 GB, see Copy Object.
parameters:
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipExpires: 3600000Success will return:
example:
var result = yield store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
});
console.log(result);
var result = yield store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
}, {
parallel: 4,
partSize: 1024 * 1024,
progress: function* (p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
console.log(result);
var result = yield store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
}, {
checkpoint: savedCpt,
progress: function* (p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
console.log(result);
//start upload
try {
var result = yield store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
}, {
checkpoint: savedCpt,
progress: function* (p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
} catch (err) {
//if cancel will catch cancel event
if (store.isCancel()) {
//do something
}
}
//the other event to cancel, for example: click event
//to cancel upload must use the same client instance
store.cancel();
The ListParts command can be used to list all successfully uploaded parts mapped to a specific upload ID, i.e.: those not completed and not aborted.
parameters:
Success will return:
example:
var result = yield store.listParts('objcet', 'uploadId', {
'max-parts': 1000
});
console.log(result);
List on-going multipart uploads, i.e.: those not completed and not aborted.
parameters:
upload-id-marker
is not provided, return uploads with key > marker, otherwise
return uploads with key >= marker && uploadId > id-markerkey-markerexample:
var result = yield store.listUploads({
'max-uploads': 100,
'key-marker': 'my-object',
'upload-id-marker': 'upload-id'
});
console.log(result);
Abort a multipart upload for object.
parameters:
example:
var result = yield store.abortMultipartUpload('object', 'upload-id');
console.log(result);
All operations function is generator, except getRtmpUrl.
generator function format: functionName*(...).
Create a live channel.
parameters:
Success will return the channel information.
object:
example:
var cid = 'my-channel';
var conf = {
Description: 'this is channel 1',
Status: 'enabled',
Target: {
Type: 'HLS',
FragDuration: '10',
FragCount: '5',
PlaylistName: 'playlist.m3u8'
}
};
var r = yield this.store.putChannel(cid, conf);
console.log(r);
Get live channel info.
parameters:
Success will return the channel information.
object:
example:
var cid = 'my-channel';
var r = yield this.store.getChannel(cid);
console.log(r);
Delete a live channel.
parameters:
Success will return the response infomation.
object:
example:
var cid = 'my-channel';
var r = yield this.store.deleteChannel(cid);
console.log(r);
Change the live channel status.
parameters:
Success will return the response information.
object:
example:
var cid = 'my-channel';
var r = yield this.store.putChannelStatus(cid, 'disabled');
console.log(r);
Get the live channel status.
parameters:
Success will return the channel status information.
object:
example:
var cid = 'my-channel';
var r = yield this.store.getChannelStatus(cid);
console.log(r);
// { Status: 'Live',
// ConnectedTime: '2016-04-12T11:51:03.000Z',
// RemoteAddr: '42.120.74.98:53931',
// Video:
// { Width: '672',
// Height: '378',
// FrameRate: '29',
// Bandwidth: '60951',
// Codec: 'H264' },
// Audio: { Bandwidth: '5959', SampleRate: '22050', Codec: 'AAC' }
// }
List channels.
parameters:
Success will return the channel list.
object:
example:
var r = yield this.store.listChannels({
prefix: 'my-channel',
'max-keys': 3
});
console.log(r);
Get the live channel history.
parameters:
Success will return the history information.
object:
example:
var cid = 'my-channel';
var r = yield this.store.getChannelHistory(cid);
console.log(r);
Create a VOD playlist for the channel.
parameters:
Success will return the response information.
object:
example:
var cid = 'my-channel';
var r = yield this.store.createVod(cid, 're-play', {
startTime: 1460464870,
endTime: 1460465877
});
console.log(r);
Get signatured rtmp url for publishing.
parameters:
Success will return the rtmp url.
example:
var cid = 'my-channel';
var url = this.store.getRtmpUrl(this.cid, {
params: {
playlistName: 'play.m3u8'
},
expires: 3600
});
console.log(url);
// rtmp://ossliveshow.oss-cn-hangzhou.aliyuncs.com/live/tl-channel?OSSAccessKeyId=T0cqQWBk2ThfRS6m&Expires=1460466188&Signature=%2BnzTtpyxUWDuQn924jdS6b51vT8%3D
Each Image Service instance required accessKeyId, accessKeySecret, bucket and imageHost.
Create a Image service instance.
options:
putBucket() create one first.oss-cn-hangzhou
Current available: oss-cn-hangzhou, oss-cn-qingdao, oss-cn-beijing, oss-cn-hongkong and oss-cn-shenzhenfalse
If your servers are running on aliyun too, you can set true to save lot of money.60sexample:
var oss = require('ali-oss');
var imgClient = oss.ImageClient({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'my_image_bucket'
imageHost: 'thumbnail.myimageservice.com'
});
All operations function is generator, except imgClient.signatureUrl.
generator function format: functionName*(...).
Get an image from the image channel.
parameters:
file is null or ignore this parameter, function will return info contains content property.Success will return the info contains response.
object:
file parameter is null or ignoreIf object not exists, will throw NoSuchKeyError.
example:
var imagepath = '/home/ossdemo/demo.jpg';
yield imgClient.get('ossdemo/demo.jpg@200w_200h', filepath);
_ Store image to a writestream
yield imgClient.get('ossdemo/demo.jpg@200w_200h', somestream);
var result = yield imgClient.get('ossdemo/demo.jpg@200w_200h');
console.log(Buffer.isBuffer(result.content));
var imagepath = '/home/ossdemo/demo.jpg';
yield imgClient.get('ossdemo/not-exists-demo.jpg@200w_200h', filepath);
// will throw NoSuchKeyError
Get an image read stream.
parameters:
Success will return the stream instance and response info.
object:
null.If object not exists, will throw NoSuchKeyError.
example:
var result = yield imgClient.getStream('ossdemo/demo.jpg@200w_200h');
result.stream.pipe(fs.createWriteStream('some demo.jpg'));
Get a image exif info by image object name from the image channel.
parameters:
Success will return the info contains response.
object:
If object don't have exif, will throw 400 BadRequest.
example:
var result = yield imgClient.getExif('demo.jpg');
// resut:
// {
// res: {
// status: 200,
// statusCode: 200,
// headers: {
// server: "Tengine",
// content - type: "application/json",
// content - length: "148",
// connection: "keep-alive",
// date: "Tue, 31 Mar 2015 11:06:32 GMT",
// "last-modified": "Mon, 30 Mar 2015 10:46:35 GMT"
// },
// size: 148,
// aborted: false,
// rt: 461,
// keepAliveSocket: false
// },
// data: {
// FileSize: 343683,
// ImageHeight: 1200,
// ImageWidth: 1600,
// Orientation: 1
// }
// }
Get a image info and exif info by image object name from the image channel.
parameters:
Success will return the info contains response.
object:
example:
var result = yield imgClient.getInfo('demo.jpg');
// resut:
// {
// res: {
// status: 200,
// statusCode: 200,
// headers: {
// server: "Tengine",
// content - type: "application/json",
// content - length: "148",
// connection: "keep-alive",
// date: "Tue, 31 Mar 2015 11:06:32 GMT",
// "last-modified": "Mon, 30 Mar 2015 10:46:35 GMT"
// },
// size: 148,
// aborted: false,
// rt: 461,
// keepAliveSocket: false
// },
// data: {
// FileSize: 343683,
// Format: "jpg",
// ImageHeight: 1200,
// ImageWidth: 1600,
// Orientation: 1
// }
// }
// TODO
Get a style by name from the image channel.
parameters:
Success will return the info contains response.
object:
example:
var result = yield imgClient.getStyle('400');
// resut:
// {
// res: {
// status: 200,
// statusCode: 200,
// headers: {
// server: "Tengine",
// content - type: "application/xml",
// content - length: "234",
// connection: "keep-alive",
// date: "Tue, 31 Mar 2015 10:58:20 GMT"
// },
// size: 234,
// aborted: false,
// rt: 398,
// keepAliveSocket: false
// },
// data: {
// Name: "400",
// Content: "400w_90Q_1x.jpg",
// CreateTime: "Thu, 19 Mar 2015 08:34:21 GMT",
// LastModifyTime: "Thu, 19 Mar 2015 08:34:21 GMT"
// }
// }
Get all styles from the image channel.
parameters:
Success will return the info contains response.
object:
example:
var result = yield imgClient.listStyle();
// resut:
// {
// res: {
// status: 200,
// statusCode: 200,
// headers: {
// server: "Tengine",
// content - type: "application/xml",
// content - length: "913",
// connection: "keep-alive",
// date: "Tue, 31 Mar 2015 10:47:32 GMT"
// },
// size: 913,
// aborted: false,
// rt: 1911,
// keepAliveSocket: false
// },
// data: [{
// Name: "200-200",
// Content: "0e_200w_200h_0c_0i_0o_90Q_1x.jpg",
// CreateTime: "Thu, 19 Mar 2015 08:28:08 GMT",
// LastModifyTime: "Thu, 19 Mar 2015 08:28:08 GMT"
// }, {
// Name: "800",
// Content: "800w_90Q_1x.jpg",
// CreateTime: "Thu, 19 Mar 2015 08:29:15 GMT",
// LastModifyTime: "Thu, 19 Mar 2015 08:29:15 GMT"
// }, {
// Name: "400",
// Content: "400w_90Q_1x.jpg",
// CreateTime: "Thu, 19 Mar 2015 08:34:21 GMT",
// LastModifyTime: "Thu, 19 Mar 2015 08:34:21 GMT"
// }, {
// Name: "600",
// Content: "600w_90Q_1x.jpg",
// CreateTime: "Thu, 19 Mar 2015 08:35:02 GMT",
// LastModifyTime: "Thu, 19 Mar 2015 08:35:02 GMT"
// }]
// }
// TODO
Create a signature url for directly download.
parameters:
1800Success will return full signature url.
example:
var url = imgClient.signatureUrl('
');
// http://thumbnail.myimageservice.com/demo.jpg@200w_200h?OSSAccessKeyId=uZxyLARzYZtGwHKY&Expires=1427803849&Signature=JSPRe06%2FjQpQSj5zlx2ld1V%2B35I%3D
Cluster mode now only support object operations.
var Cluster = require('ali-oss').ClusterClient;
var client = Cluster({
cluster: [{
host: 'host1',
accessKeyId: 'id1',
accessKeySecret: 'secret1'
}, {
host: 'host2',
accessKeyId: 'id2',
accessKeySecret: 'secret2'
}],
schedule: 'masterSlave', //default is `roundRobin`
});
// listen error event to logging error
client.on('error', function(err) {
console.error(err.stack);
});
// client init ready
client.ready(function() {
console.log('cluster client init ready, go ahead!');
});
Will choose an alive client by schedule(masterSlave or roundRobin).
client.get()client.head()client.getStream()client.list()client.signatureUrl()client.chooseAvailable() - choose an available client by schedule.client.getACL()Will put to all clients.
client.put()client.putStream()client.delete()client.deleteMulti()client.copy()client.putMeta()client.putACL()client.restore()We provide an async wrapper which can be used without co. All the
methods are preserved, just in a async way:
var OSS = require('ali-oss').Wrapper;
var STS = OSS.STS;
var client = new OSS({ /* same options */});
client.put('hello', new Buffer('world')).then(function (val) {
console.log('result: %j', val);
}).catch (function (err) {
console.log('error: %j', err);
});
client.get('hello').then(function (val) {
console.log('result: %j', val);
}).catch (function (err) {
console.log('error: %j', err);
});
var url = client.signatureUrl('hello');
console.log(url);
var stsClient = new STS({ /* same options */});
var role = 'role';
stsClient.assumeRole(role).then(function (val) {
console.log('result: %j', val);
}).catch (function (err) {
console.log('error: %j', err);
});
You can use most of the functionalities of ali-oss in browser with
some exceptions:
As browser-side javascript involves CORS operations. You need to setup your bucket CORS rules to allow CORS operations:
As we don't want to expose the accessKeyId/accessKeySecret in the browser, a common practice is to use STS to grant temporary access.
Include the sdk lib in the <script> tag and you have OSS available
for creating client. We use OSS.Wrapper here to avoid using co:
// x.x.x The specific version number represented
// we recommend introducing offline resources, because the usability of online resources depends on the stability of the cdn server.
<!-- Introducing online resources -->
<script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
<!-- Introducing offline resources -->
<script src="./aliyun-oss-sdk-x.x.x.min.js"></script>
<script type="text/javascript">
var client = new OSS.Wrapper({
region: 'oss-cn-hangzhou',
accessKeyId: '<access-key-id>',
accessKeySecret: '<access-key-secret>',
bucket: '<bucket-name>'
});
client.list().then(function (result) {
console.log('objects: %j', result.objects);
return client.put('my-obj', new OSS.Buffer('hello world'));
}).then(function (result) {
console.log('put result: %j', result);
return client.get('my-obj');
}).then(function (result) {
console.log('get result: %j', result.content.toString());
});
</script>
The full sample can be found here.
npm run build-dist
And see the build artifacts under dist/.
Each error return by OSS server will contains these properties:
| name | code | status | message | message in Chinese |
|---|---|---|---|---|
| AccessDeniedError | AccessDenied | 403 | Access Denied | 拒绝访问 |
| BucketAlreadyExistsError | BucketAlreadyExists | 409 | Bucket already exists | Bucket 已经存在 |
| BucketNotEmptyError | BucketNotEmpty | 409 | Bucket is not empty | Bucket 不为空 |
| RestoreAlreadyInProgressError | RestoreAlreadyInProgress | 409 | The restore operation is in progress. | restore 操作正在进行中 |
| OperationNotSupportedError | OperationNotSupported | 400 | The operation is not supported for this resource | 该资源暂不支持restore操作 |
| EntityTooLargeError | EntityTooLarge | 400 | Entity too large | 实体过大 |
| EntityTooSmallError | EntityTooSmall | 400 | Entity too small | 实体过小 |
| FileGroupTooLargeError | FileGroupTooLarge | 400 | File group too large | 文件组过大 |
| InvalidLinkNameError | InvalidLinkName | 400 | Link name can't be the same as the object name | Object Link 与指向的 Object 同名 |
| LinkPartNotExistError | LinkPartNotExist | 400 | Can't link to not exists object | Object Link 中指向的 Object 不存在 |
| ObjectLinkTooLargeError | ObjectLinkTooLarge | 400 | Too many links to this object | Object Link 中 Object 个数过多 |
| FieldItemTooLongError | FieldItemTooLong | 400 | Post form fields items too large | Post 请求中表单域过大 |
| FilePartInterityError | FilePartInterity | 400 | File part has changed | 文件 Part 已改变 |
| FilePartNotExistError | FilePartNotExist | 400 | File part not exists | 文件 Part 不存在 |
| FilePartStaleError | FilePartStale | 400 | File part stale | 文件 Part 过时 |
| IncorrectNumberOfFilesInPOSTRequestError | IncorrectNumberOfFilesInPOSTRequest | 400 | Post request contains invalid number of files | Post 请求中文件个数非法 |
| InvalidArgumentError | InvalidArgument | 400 | Invalid format argument | 参数格式错误 |
| InvalidAccessKeyIdError | InvalidAccessKeyId | 400 | Access key id not exists | Access Key ID 不存在 |
| InvalidBucketNameError | InvalidBucketName | 400 | Invalid bucket name | 无效的 Bucket 名字 |
| InvalidDigestError | InvalidDigest | 400 | Invalid digest | 无效的摘要 |
| InvalidEncryptionAlgorithmError | InvalidEncryptionAlgorithm | 400 | Invalid encryption algorithm | 指定的熵编码加密算法错误 |
| InvalidObjectNameError | InvalidObjectName | 400 | Invalid object name | 无效的 Object 名字 |
| InvalidPartError | InvalidPart | 400 | Invalid part | 无效的 Part |
| InvalidPartOrderError | InvalidPartOrder | 400 | Invalid part order | 无效的 part 顺序 |
| InvalidPolicyDocumentError | InvalidPolicyDocument | 400 | Invalid policy document | 无效的 Policy 文档 |
| InvalidTargetBucketForLoggingError | InvalidTargetBucketForLogging | 400 | Invalid bucket on logging operation | Logging 操作中有无效的目标 bucket |
| InternalError | Internal | 500 | OSS server internal error | OSS 内部发生错误 |
| MalformedXMLError | MalformedXML | 400 | Malformed XML format | XML 格式非法 |
| MalformedPOSTRequestError | MalformedPOSTRequest | 400 | Invalid post body format | Post 请求的 body 格式非法 |
| MaxPOSTPreDataLengthExceededError | MaxPOSTPreDataLengthExceeded | 400 | Post extra data too large | Post 请求上传文件内容之外的 body 过大 |
| MethodNotAllowedError | MethodNotAllowed | 405 | Not allowed method | 不支持的方法 |
| MissingArgumentError | MissingArgument | 411 | Missing argument | 缺少参数 |
| MissingContentLengthError | MissingContentLength | 411 | Missing Content-Length header | 缺少内容长度 |
| NoSuchBucketError | NoSuchBucket | 404 | Bucket not exists | Bucket 不存在 |
| NoSuchKeyError | NoSuchKey | 404 | Object not exists | 文件不存在 |
| NoSuchUploadError | NoSuchUpload | 404 | Multipart upload id not exists | Multipart Upload ID 不存在 |
| NotImplementedError | NotImplemented | 501 | Not implemented | 无法处理的方法 |
| PreconditionFailedError | PreconditionFailed | 412 | Pre condition failed | 预处理错误 |
| RequestTimeTooSkewedError | RequestTimeTooSkewed | 403 | Request time exceeds 15 minutes to server time | 发起请求的时间和服务器时间超出 15 分钟 |
| RequestTimeoutError | RequestTimeout | 400 | Request timeout | 请求超时 |
| RequestIsNotMultiPartContentError | RequestIsNotMultiPartContent | 400 | Invalid post content-type | Post 请求 content-type 非法 |
| SignatureDoesNotMatchError | SignatureDoesNotMatch | 403 | Invalid signature | 签名错误 |
| TooManyBucketsError | TooManyBuckets | 400 | Too many buckets on this user | 用户的 Bucket 数目超过限制 |
| RequestError | RequestError | -1 | network error | 网络出现中断或异常 |
| ConnectionTimeoutError | ConnectionTimeoutError | -2 | request connect timeout | 请求连接超时 |
| SecurityTokenExpiredError | SecurityTokenExpired | 403 | sts Security Token Expired | sts Security Token 超时失效 |
FAQs
aliyun oss(object storage service) node client
The npm package ali-oss receives a total of 49,298 weekly downloads. As such, ali-oss popularity was classified as popular.
We found that ali-oss demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.