aliyun OSS(Object Storage Service) js client for Node and Browser env.
NOTE： For SDK 5.X document, please go to README.md
npm install ali-oss --save
Node.js >= 8.0.0 required. You can use 4.x in Node.js < 8.
Note:
Please log in to the official website and contact technical support.
OSS, Object Storage Service. Equal to well known Amazon S3.
All operation use es7 async/await to implement. All api is async function.
1.install SDK using npm
npm install ali-oss --save
2.for example:
const OSS = require('ali-oss');
const store = new OSS({
region: '<oss region>',
accessKeyId: '<Your accessKeyId>',
accessKeySecret: '<Your accessKeySecret>',
bucket: '<Your bucket name>'
});
You can use most of the functionalities of ali-oss in browser with
some exceptions:
Note: Because some browsers do not support promises, you need to introduce promise compatible libraries.
For example: IE10 and IE11 need to introduce a promise-polyfill.
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.
// 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">
const store = new OSS({
region: 'oss-cn-hangzhou',
accessKeyId: '<access-key-id>',
accessKeySecret: '<access-key-secret>',
bucket: '<bucket-name>',
stsToken: '<security-token>'
});
store
.list()
.then(result => {
console.log('objects: %j', result.objects);
return store.put('my-obj', new OSS.Buffer('hello world'));
})
.then(result => {
console.log('put result: %j', result);
return store.get('my-obj');
})
.then(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/.
| 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:
stsToken、accessKeyId、accessKeySecret when sts info expires. return value must be object contains stsToken、accessKeyId、accessKeySecretputBucket() create one first.region. Set as extranet domain name, intranet domain name, accelerated domain name, etc. according to different needs. please see endpointsoss-cn-hangzhou.false.
If your servers are running on aliyun too, you can set true to save a lot of money.60s.endpoint field with your custom domain name,'x-oss-request-payer': 'requester' to oss server.
the details you can see requestPayfetch mode ,else XMLHttpRequestput with stream, putStream, append with stream because the stream can only be consumed onceexample:
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
region: 'oss-cn-hangzhou'
});
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
endpoint: 'oss-accelerate.aliyuncs.com'
});
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
cname: true,
endpoint: 'your custome domain'
});
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your STS key',
accessKeySecret: 'your STS secret',
stsToken: 'your STS token',
refreshSTSToken: async () => {
const info = await fetch('you sts server');
return {
accessKeyId: info.accessKeyId,
accessKeySecret: info.accessKeySecret,
stsToken: info.stsToken
};
},
refreshSTSTokenInterval: 300000
});
for (let i = 0; i <= store.options.retryMax; i++) {
try {
const result = await store.putStream('<example-object>', fs.createReadStream('<example-path>'));
console.log(result);
break; // break if success
} catch (e) {
console.log(e);
}
}
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'your bucket name',
region: 'oss-cn-hangzhou',
authorizationV4: true
});
try {
const bucketInfo = await store.getBucketInfo('your bucket name');
console.log(bucketInfo);
} catch (e) {
console.log(e);
}
try {
const putObjectResult = await store.put('your bucket name', 'your object name', {
headers: {
// The headers of this request
header1: 'value1',
header2: 'value2'
},
// The keys of the request headers that need to be calculated into the V4 signature. Please ensure that these additional headers are included in the request headers.
additionalHeaders: ['additional header1', 'additional header2']
});
console.log(putObjectResult);
} catch (e) {
console.log(e);
}
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.000ZStandard, IA, Archiveid and displayNameexample:
store
.listBuckets({
'max-keys': 10
})
.then(result => {
console.log(result);
});
Create a new bucket.
parameters:
private,public-read,public-read-writeLRS, include LRS,ZRSSuccess will return the bucket name on bucket properties.
example:
helloworld location on HongKongstore.putBucket('helloworld').then(result => {
// use it by default
store.useBucket('helloworld');
});
helloworld location on HongKong StorageClass Archiveawait store.putBucket('helloworld', { StorageClass: 'Archive' });
// use it by default
store.useBucket('helloworld');
Delete an empty bucket.
parameters:
Success will return:
example:
store.deleteBucket('helloworld').then(result => {});
Use the bucket.
parameters:
example:
helloworld as the default bucketstore.useBucket('helloworld');
Get bucket information,include CreationDate、ExtranetEndpoint、IntranetEndpoint、Location、Name、StorageClass、 Owner、AccessControlList、Versioning
parameters:
example:
helloworld as the default bucketstore.getBucketInfo('helloworld').then(res => {
console.log(res.bucket);
});
Call the GetBucketStat interface to get the storage capacity of the specified storage space (Bucket) and the number of files (Object).
Calling this interface requires the oss:GetBucketStat permission. The data obtained by calling this interface is not real-time data and may be delayed for more than an hour. The point in time of the stored information obtained by calling this interface is not guaranteed to be up-to-date, i.e. the LastModifiedTime field returned by a later call to this interface may be smaller than the LastModifiedTime field returned by a previous call to this interface.
parameters:
Success will return:
stat {Object} container for the BucketStat structure:
res {Object} response info, including
example:
store.getBucketStat().then(res => console.log(res));
Get bucket location
parameters:
example:
helloworld as the default bucketstore.getBucketLocation('helloworld').then(res => {
console.log(res.location);
});
Update the bucket ACL.
parameters:
public-read-write, public-read and privateSuccess will return:
example:
helloworld to public-read-writestore.putBucketACL('helloworld', 'public-read-write').then(result => {});
Get the bucket ACL.
parameters:
Success will return:
example:
helloworldstore.getBucketACL('helloworld').then(result => {
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:
Success will return:
example:
helloworld logging and save with prefix logs/store.putBucketLogging('helloworld', 'logs/').then(result => {});
Get the bucket logging settings.
parameters:
Success will return:
nullexample:
helloworld logging settingsstore.getBucketLogging('helloworld').then(result => {
console.log(result.enable, result.prefix);
});
Delete the bucket logging settings.
parameters:
Success will return:
Set the bucket as a static website.
parameters:
index.htmlSuccess will return:
example:
store
.putBucketWebsite('hello', {
index: 'index.html'
})
.then(result => {});
Get the bucket website config.
parameters:
Success will return:
nullDelete the bucket website config.
parameters:
Success will return:
Set the bucket request Referer white list.
parameters:
Referer white list, e.g.:
['https://npm.taobao.org', 'http://cnpmjs.org'];
Success will return:
example:
store.putBucketReferer('hello', false, ['https://npm.taobao.org', 'http://cnpmjs.org']).then(result => {});
Get the bucket request Referer white list.
parameters:
Success will return:
Referer white listDelete the bucket request Referer white list.
parameters:
Success will return:
Set the bucket object lifecycle.
parameters:
Rule will contains blow properties:
Enabled or Disableddays2022-10-11T00:00:00.000Ztrue
createdBeforeDate and days and expiredObjectDeleteMarker must have one.days2022-10-11T00:00:00.000Z
createdBeforeDate and days must have one.IA or Archive or ColdArchive or DeepColdArchivedays2022-10-11T00:00:00.000Z
createdBeforeDate and days must have one.IA or Archive or ColdArchive or DeepColdArchivenoncurrentDays
expiration、 abortMultipartUpload、 transition、 noncurrentVersionTransition must have one.noncurrentDaystag cannot be used with abortMultipartUploadSuccess will return:
example:
store
.putBucketLifecycle('hello', [
{
id: 'delete after one day',
prefix: 'logs/',
status: 'Enabled',
days: 1
},
{
prefix: 'logs2/',
status: 'Disabled',
date: '2022-10-11T00:00:00.000Z'
}
])
.then(result => {});
example: for history with noncurrentVersionExpiration
const result = await store.putBucketLifecycle(bucket, [
{
id: 'expiration1',
prefix: 'logs/',
status: 'Enabled',
expiration: {
days: '1'
},
noncurrentVersionExpiration: {
noncurrentDays: '1'
}
}
]);
console.log(result);
example: for history with expiredObjectDeleteMarker
const result = await store.putBucketLifecycle(bucket, [
{
id: 'expiration1',
prefix: 'logs/',
status: 'Enabled',
expiration: {
expiredObjectDeleteMarker: 'true'
},
noncurrentVersionExpiration: {
noncurrentDays: '1'
}
}
]);
console.log(result);
example: for history with noncurrentVersionTransition
const result = await store.putBucketLifecycle(bucket, [
{
id: 'expiration1',
prefix: 'logs/',
status: 'Enabled',
noncurrentVersionTransition: {
noncurrentDays: '10',
storageClass: 'IA'
}
}
]);
console.log(result);
Get the bucket object lifecycle.
parameters:
Success will return:
Delete the bucket object lifecycle.
parameters:
Success will return:
Set CORS rules of the bucket object
parameters:
Rule will contains below properties:
Success will return:
example:
store
.putBucketCORS('hello', [
{
allowedOrigin: '*',
allowedMethod: ['GET', 'HEAD']
}
])
.then(result => {});
Get CORS rules of the bucket object.
parameters:
Success will return:
Delete CORS rules of the bucket object.
parameters:
Success will return:
get RequestPayment value of the bucket object.
parameters:
Success will return:
put RequestPayment value of the bucket object.
parameters:
Success will return:
put BucketEncryption value of the bucket object.
parameters:
Success will return:
get BucketEncryption rule value of the bucket object.
parameters:
Success will return:
delete BucketEncryption rule value of the bucket object.
parameters:
Success will return:
Adds tags for a bucket or modify the tags for a bucket.
parameters:
{var1: value1,var2:value2}Success will return:
Obtains the tags for a bucket.
parameters:
Success will return:
Deletes the tags added for a bucket.
parameters:
Success will return:
Adds or modify policy for a bucket.
parameters:
Success will return:
example:
const policy = {
Version: '1',
Statement: [
{
Action: ['oss:PutObject', 'oss:GetObject'],
Effect: 'Deny',
Principal: ['1234567890'],
Resource: ['acs:oss:*:1234567890:*/*']
}
]
};
const result = await store.putBucketPolicy(bucket, policy);
console.log(result);
Obtains the policy for a bucket.
parameters:
Success will return:
Deletes the policy added for a bucket.
parameters:
Success will return:
Obtains the version status of an object
parameters:
Success will return:
Suspended or Enabled. default value: undefinedset the version status of an object
parameters:
Enabled or SuspendedSuccess will return:
get bucket inventory by inventory-id
parameters:
Success will return:
async function getBucketInventoryById() {
try {
const result = await store.getBucketInventory('bucket', 'inventoryid');
console.log(result.inventory);
} catch (err) {
console.log(err);
}
}
getBucketInventoryById();
set bucket inventory
parameters:
Success will return:
type Field =
'Size | LastModifiedDate | ETag | StorageClass | IsMultipartUploaded | EncryptionStatus | ObjectAcl | TaggingCount | ObjectType | Crc64';
interface Inventory {
id: string;
isEnabled: true | false;
prefix?: string;
OSSBucketDestination: {
format: 'CSV';
accountId: string;
rolename: string;
bucket: string;
prefix?: string;
encryption?:
| { 'SSE-OSS': '' }
| {
'SSE-KMS': {
keyId: string;
};
};
};
frequency: 'Daily' | 'Weekly';
includedObjectVersions: 'Current' | 'All';
optionalFields?: {
field?: Field[];
};
}
const inventory = {
id: 'default',
isEnabled: false, // `true` | `false`
prefix: 'ttt', // filter prefix
OSSBucketDestination: {
format: 'CSV',
accountId: '1817184078010220',
rolename: 'AliyunOSSRole',
bucket: 'your bucket',
prefix: 'test'
//encryption: {'SSE-OSS': ''},
/*
encryption: {
'SSE-KMS': {
keyId: 'test-kms-id';
};,
*/
},
frequency: 'Daily', // `WEEKLY` | `Daily`
includedObjectVersions: 'All', // `All` | `Current`
optionalFields: {
field: [
'Size',
'LastModifiedDate',
'ETag',
'StorageClass',
'IsMultipartUploaded',
'EncryptionStatus',
'ObjectAcl',
'TaggingCount',
'ObjectType',
'Crc64'
]
}
};
async function putInventory() {
const bucket = 'Your Bucket Name';
try {
await store.putBucketInventory(bucket, inventory);
} catch (err) {
console.log(err);
}
}
putInventory();
delete bucket inventory by inventory-id
parameters:
Success will return:
list bucket inventory
parameters:
Success will return:
example:
async function listBucketInventory() {
const bucket = 'Your Bucket Name';
let nextContinuationToken;
// list all inventory of the bucket
do {
const result = await store.listBucketInventory(bucket, nextContinuationToken);
console.log(result.inventoryList);
nextContinuationToken = result.nextContinuationToken;
} while (nextContinuationToken);
}
listBucketInventory();
used to delete an unlocked retention policy.
parameters:
Success will return:
used to lock a retention policy.
parameters:
Success will return:
used to extend the retention period of objects in a bucket whose retention policy is locked.
parameters:
Success will return:
used to query the retention policy information of the specified bucket.
parameters:
Success will return:
Locked or InProgresscreate a retention policy.
parameters:
Success will return:
All operations function return Promise, except signatureUrl.
Add an object to the bucket.
parameters:
Content-Type entity headerx-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }key=${key}&etag=${etag}&my_var=${x:my_var}.var customValue = { var1: 'value1', var2: 'value2' };
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipTue, 08 Dec 2020 13:49:43 GMTSuccess will return the object information.
object:
example:
const filepath = '/home/ossdemo/demo.txt';
store.put('ossdemo/demo.txt', filepath).then((result) => {
console.log(result);
});
// {
// 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
// }
// }
store.put('ossdemo/buffer', Buffer.from('foo content')).then((result) => {
console.log(result);
});
// {
// 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
// }
// }
const filepath = '/home/ossdemo/demo.txt';
store.put('ossdemo/readstream.txt', fs.createReadStream(filepath)).then((result) => {
console.log(result);
});
// {
// 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: gzipTue, 08 Dec 2020 13:49:43 GMTSuccess will return the object information.
object:
example:
const filepath = '/home/ossdemo/demo.txt';
store.putStream('ossdemo/readstream.txt', fs.createReadStream(filepath)).then((result) => {
console.log(result);
});
// {
// 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: gzipTue, 08 Dec 2020 13:49:43 GMTobject:
example:
let object = await store.append('ossdemo/buffer', Buffer.from('foo'));
// append content to the existing object
object = await store.append('ossdemo/buffer', Buffer.from('bar'), {
position: object.nextAppendPosition
});
Get the Object url.
If provide baseUrl, will use baseUrl instead the default endpoint.
e.g.:
const cdnUrl = store.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 = store.generateObjectUrl('foo/bar.jpg');
// cdnUrl should be `https://${bucketname}.${endpotint}foo/bar.jpg`
const cdnUrl = store.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:
await this.store.put('ossdemo/head-meta', Buffer.from('foo'), {
meta: {
uid: 1,
path: 'foo/demo.txt'
}
});
const object = await this.store.head('ossdemo/head-meta');
console.log(object);
// {
// status: 200,
// meta: {
// uid: '1',
// path: 'foo/demo.txt'
// },
// res: { ... }
// }
const object = await this.store.head('ossdemo/head-meta');
// will throw NoSuchKeyError
Get an object meta info include ETag、Size、LastModified and so on, not return object content.
parameters:
Success will return the object's meta information.
object:
example:
await this.store.put('ossdemo/object-meta', Buffer.from('foo'));
const object = await this.store.getObjectMeta('ossdemo/object-meta');
console.log(object);
// {
// status: 200,
// res: { ... }
// }
Get an object from the bucket.
parameters:
file is null or ignore this parameter, function will return info contains content property.
If file is Object, it will be treated as options.x-oss-process
e.g.: {process: 'image/resize,w_200'}no-cache, (only support Browser). response-cache-control, will response with HTTP Header Cache-ControlRange: bytes=0-9Success will return the info contains response.
object:
file parameter is null or ignoreIf object not exists, will throw NoSuchKeyError.
example:
const filepath = '/home/ossdemo/demo.txt';
await store.get('ossdemo/demo.txt', filepath);
_ Store object to a writestream
await store.get('ossdemo/demo.txt', somestream);
const result = await store.get('ossdemo/demo.txt');
console.log(Buffer.isBuffer(result.content));
const filepath = '/home/ossdemo/demo.png';
await store.get('ossdemo/demo.png', filepath, { process: 'image/resize,w_200' });
const filepath = '/home/ossdemo/demo.txt';
await store.get('ossdemo/not-exists-demo.txt', filepath);
// will throw NoSuchKeyError
const filepath = '/home/ossdemo/demo.txt';
const versionId = 'versionId string';
await store.get('ossdemo/not-exists-demo.txt', filepath, {
versionId
});
file is Object, it will be treated as options.const versionId = 'versionId string';
await store.get('ossdemo/not-exists-demo.txt', { versionId });
Get an object read stream.
parameters:
x-oss-processSuccess will return the stream instance and response info.
object:
200, stream will be null.If object not exists, will throw NoSuchKeyError.
example:
const result = await 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:
await store.delete('ossdemo/someobject');
await store.delete('ossdemo/some-not-exists-object');
const versionId = 'versionId';
await store.delete('ossdemo/some-not-exists-object', { versionId });
Copy an object from sourceName to name.
parameters:
sourceBucket is same 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:
store.copy('newName', 'oldName').then(result => {
console.log(result);
});
store.copy('logo.png', 'logo.png', 'other-bucket').then(result => {
console.log(result);
});
const versionId = 'your verisonId';
store.copy('logo.png', 'logo.png', 'other-bucket', { versionId }).then(result => {
console.log(result);
});
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 putMeta result in data property.
2015-02-19T08:39:44.000Z", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"If object not exists, will throw NoSuchKeyError.
example:
const result = await store.putMeta('ossdemo.txt', {
uid: 1,
pid: 'p123'
});
console.log(result);
await 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:
const result = await store.deleteMulti(['obj1', 'obj2', 'obj3'], {
quiet: true
});
const result = await store.deleteMulti(['obj1', 'obj2', 'obj3']);
const obj1 = {
key: 'key1',
versionId: 'versionId1'
};
const obj2 = {
key: 'key2',
versionId: 'versionId2'
};
const result = await store.deleteMulti([obj1, obj2]);
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:
const result = await store.list();
console.log(result.objects);
fun/ dir including subdirs objectsconst result = await store.list({
prefix: 'fun/'
});
console.log(result.objects);
fun/ dir objects, not including subdirsconst result = await store.list({
prefix: 'fun/',
delimiter: '/'
});
console.log(result.objects);
List objects in the bucket.(recommended)
parameters:
null
prefix keycontinuationToken, including continuationToken key/ only search current dir, not including subdir100, limit to 1000Success will return objects list on objects properties.
objects {Array} object meta info list
Each ObjectMeta will contains blow properties:
2015-02-19T08:39:44.000Z", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"Normal344606Standardid and displayNameprefixes {Array} prefix list
isTruncated {Boolean} truncate or not
nextContinuationToken {String} next continuation-token string
keyCount {Number} The number of keys returned for this request. If Delimiter is specified, KeyCount is the sum of the elements in Key and CommonPrefixes.
res {Object} response info, including
List top 10 objects
const result = await store.listV2({
'max-keys': 10
});
console.log(result.objects);
fun/ dir including subdirs objectsconst result = await store.listV2({
prefix: 'fun/'
});
console.log(result.objects);
fun/ dir objects, not including subdirsconst result = await store.listV2({
prefix: 'fun/',
delimiter: '/'
});
console.log(result.objects);
a/ dir objects, after a/b and not include a/bconst result = await store.listV2({
delimiter: '/',
prefix: 'a/',
'start-after': 'a/b'
});
console.log(result.objects);
List the version information of all objects in the bucket, including the delete marker (Delete Marker).
parameters:
null
prefix keykeyMarker, including keyMarker 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 displayNameObjectDeleteMarker
2015-02-19T08:39:44.000Zexample:
const result = await store.getBucketVersions();
console.log(result.objects);
console.log(result.deleteMarker);
const result = await store.getBucketVersions({
keyMarker: 'keyMarker'
});
console.log(result.objects);
const result = await store.getBucketVersions({
versionIdMarker: 'versionIdMarker',
keyMarker: 'keyMarker'
});
console.log(result.objects);
console.log(result.deleteMarker);
Create a signature url for download or upload object. When you put object with signatureUrl ,you need to pass Content-Type.Please look at the example.
parameters:
1800x-oss-process
e.g.: {process: 'image/resize,w_200'}819200~838860800.Success will return signature url.
example:
const url = store.signatureUrl('ossdemo.txt');
console.log(url);
// --------------------------------------------------
const url = store.signatureUrl('ossdemo.txt', {
expires: 3600,
method: 'PUT'
});
console.log(url);
// put object with signatureUrl
// -------------------------------------------------
const url = store.signatureUrl('ossdemo.txt', {
expires: 3600,
method: 'PUT',
'Content-Type': 'text/plain; charset=UTF-8'
});
console.log(url);
// --------------------------------------------------
const url = store.signatureUrl(
'ossdemo.txt',
{
expires: 3600,
response: {
'content-type': 'text/custom',
'content-disposition': 'attachment'
}
},
false
);
console.log(url);
// put operation
const url = store.signatureUrl('ossdemo.png', {
process: 'image/resize,w_200'
});
console.log(url);
// --------------------------------------------------
const url = store.signatureUrl('ossdemo.png', {
expires: 3600,
process: 'image/resize,w_200'
});
console.log(url);
Basically the same as signatureUrl, if refreshSTSToken is configured asyncSignatureUrl will refresh stsToken
parameters:
1800x-oss-process
e.g.: {process: 'image/resize,w_200'}819200~838860800.Success will return signature url.
example:
const url = await store.asyncSignatureUrl('ossdemo.txt');
console.log(url);
// --------------------------------------------------
const url = await store.asyncSignatureUrl('ossdemo.txt', {
expires: 3600,
method: 'PUT'
});
console.log(url);
// put object with signatureUrl
// -------------------------------------------------
const url = await store.asyncSignatureUrl('ossdemo.txt', {
expires: 3600,
method: 'PUT',
'Content-Type': 'text/plain; charset=UTF-8'
});
console.log(url);
// --------------------------------------------------
const url = await store.asyncSignatureUrl(
'ossdemo.txt',
{
expires: 3600,
response: {
'content-type': 'text/custom',
'content-disposition': 'attachment'
}
},
false
);
console.log(url);
// put operation
const url = await store.asyncSignatureUrl('ossdemo.png', {
process: 'image/resize,w_200'
});
console.log(url);
// --------------------------------------------------
const url = await store.asyncSignatureUrl('ossdemo.png', {
expires: 3600,
process: 'image/resize,w_200'
});
console.log(url);
Generate a signed URL for V4 of an OSS resource and share the URL to allow authorized third-party users to access the resource.
parameters:
Success will return signature url.
example:
// GetObject
const getObjectUrl = await store.signatureUrlV4('GET', 60, undefined, 'your obejct name');
console.log(getObjectUrl);
// --------------------------------------------------
const getObjectUrl = await store.signatureUrlV4(
'GET',
60,
{
headers: {
'Cache-Control': 'no-cache'
},
queries: {
versionId: 'version ID of your object'
}
},
'your obejct name',
['Cache-Control']
);
console.log(getObjectUrl);
// -------------------------------------------------
// PutObject
const putObejctUrl = await store.signatureUrlV4('PUT', 60, undefined, 'your obejct name');
console.log(putObejctUrl);
// --------------------------------------------------
const putObejctUrl = await store.signatureUrlV4(
'PUT',
60,
{
headers: {
'Content-Type': 'text/plain',
'Content-MD5': 'xxx',
'Content-Length': 1
}
},
'your obejct name',
['Content-Length']
);
console.log(putObejctUrl);
Set object's ACL.
parameters:
Success will return:
example:
await store.putACL('ossdemo.txt', 'public-read');
const versionId = 'object versionId';
await store.putACL('ossdemo.txt', 'public-read', {
versionId
});
Get object's ACL.
parameters:
Success will return:
example:
const result = await store.getACL('ossdemo.txt');
console.log(result.acl);
const versionId = 'object versionId';
const result = await store.getACL('ossdemo.txt', { versionId });
console.log(result.acl);
Restore Object.
parameters:
Success will return:
example:
const result = await store.restore('ossdemo.txt');
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'ColdArchive' });
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'ColdArchive', Days: 2 });
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'ColdArchive', Days: 2, JobParameters: 'Standard' });
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'DeepColdArchive' });
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'DeepColdArchive', Days: 2 });
console.log(result.status);
const result = await store.restore('ossdemo.txt', { type: 'DeepColdArchive', Days: 2, JobParameters: 'Standard' });
console.log(result.status);
const versionId = 'object versionId';
const result = await store.restore('ossdemo.txt', { versionId });
console.log(result.status);
PutSymlink
parameters:
name {String} object name
targetName {String} target object name
[options] {Object} optional parameters
x-oss-meta- prefix stringres {Object} response info, including
example:
const options = {
storageClass: 'IA',
meta: {
uid: '1',
slus: 'test.html'
}
};
const result = await store.putSymlink('ossdemo.txt', 'targetName', options);
console.log(result.res);
putSymlink multiversion
const options = {
storageClass: 'IA',
meta: {
uid: '1',
slus: 'test.html'
}
};
const result = await store.putSymlink('ossdemo.txt', 'targetName', options);
console.log(result.res.headers['x-oss-version-id']);
GetSymlink
parameters:
Success will return
example:
const result = await store.getSymlink('ossdemo.txt');
console.log(result.targetName);
for history object
const versionId = 'object versionId';
const result = await store.getSymlink('ossdemo.txt', { versionId });
console.log(result.targetName);
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: gzipTue, 08 Dec 2020 13:49:43 GMTx-oss-server-side-encryption: AES256Success will return:
example:
const result = await 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:
const name = 'object';
const result = await store.initMultipartUpload(name);
const uploadId = result.uploadId;
const file; //the data you want to upload, is a File or FileName(only in node)
//if file part is 10
const partSize = 100 * 1024;
const fileSize = 10 * partSize;//you need to calculate
const dones = [];
for (let i = 1; i <= 10; i++) {
const start = partSize * (i -1);
const end = Math.min(start + partSize, fileSize);
const part = await 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:
const name = 'object';
const result = await store.initMultipartUpload(name);
const partSize = 100 * 1024; //100kb
//if file part is 10
for (let i = 1; i <= 10; i++) {
const start = partSize * (i - 1);
const end = Math.min(start + partSize, fileSize);
const range = start + '-' + (end - 1);
const part = await store.uploadPartCopy(name, result.uploadId, i, range, {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
});
console.log(part);
}
//end need complete api
const versionId = 'object versionId';
const name = 'object';
const result = await store.initMultipartUpload(name);
const partSize = 100 * 1024; //100kb
//if file part is 10
for (let i = 1; i <= 10; i++) {
const start = partSize * (i - 1);
const end = Math.min(start + partSize, fileSize);
const range = start + '-' + (end - 1);
const part = await store.uploadPartCopy(
name,
result.uploadId,
i,
range,
{
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
},
{
versionId
}
);
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
const name = 'object';
const result = await store.initMultipartUpload(name);
//upload part
const file; //the data you want to upload, this example size is 10 * 100 * 1024
const fileSize;//you need to calculate
const partSize = 100 * 1024;//100kb
const done = [];
//if file part is 10
for (let i = 1; i <= 10; i++) {
const start = partSize * (i -1);
const end = Math.min(start + partSize, fileSize);
const data = file.slice(start, end);
const part = store.uploadPart(name, result.uploadId, i, data, 0, data.length);
console.log(part);
done.push({
number: i,
etag: part.res.headers.etag
});
}
//complete
const completeData = await store.completeMultipartUpload(name, result.uploadId, done);
console.log(completeData);
Upload file with OSS multipart.
this function contains initMultipartUpload, uploadPart, completeMultipartUpload.
When you use multipartUpload api，if you encounter problems with ConnectionTimeoutError, you should handle ConnectionTimeoutError in your business code. How to resolve ConnectionTimeoutError, you can decrease partSize size 、 Increase timeout 、Retry request ,
or give tips in your business code;
parameters:
1024 * 1024(1MB), minimum 100 * 1024(100KB)x-oss-meta- prefix stringContent-Type entity headervar customValue = { var1: 'value1', var2: 'value2' };
Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipTue, 08 Dec 2020 13:49:43 GMTSuccess will return:
example:
const result = await store.multipartUpload('object', '/tmp/file');
let savedCpt;
console.log(result);
const result = await store.multipartUpload('object', '/tmp/file', {
parallel: 4,
partSize: 1024 * 1024,
progress: function (p, cpt, res) {
console.log(p);
savedCpt = cpt;
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
});
const result = await 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']);
}
});
//async function
async function asyncProgress(p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
const result1 = await store.multipartUpload('object', '/tmp/file', {
progress: asyncProgress
});
//function
function progress(p, cpt, res) {
console.log(p);
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
const result2 = await store.multipartUpload('object', '/tmp/file', {
progress: progress
});
tips: abort multipartUpload support on node and browser
//start upload
let abortCheckpoint;
store.multipartUpload('object', '/tmp/file', {
progress: function (p, cpt, res) {
abortCheckpoint = cpt;
}
}).then(res => {
// do something
}).catch(err => {
//if abort will catch abort event
if (err.name === 'abort') {
// handle abort
console.log('error: ', err.message)
}
});
// abort
store.abortMultipartUpload(abortCheckpoint.name, abortCheckpoint.uploadId);
tips: cancel multipartUpload support on node and browser
//start upload
try {
const result = await 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();
ConnectionTimeoutError error//start upload
try {
const result = await 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 (err.code === 'ConnectionTimeoutError') {
console.log('Woops,Woops ,timeout error!!!');
// do ConnectionTimeoutError operation
}
}
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:
1024 * 1024(1MB), minimum 100 * 1024(100KB)Cache-Control: public, no-cacheContent-Disposition: somenameContent-Encoding: gzipTue, 08 Dec 2020 13:49:43 GMTSuccess will return:
example:
const result = await store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
});
let savedCpt;
console.log(result);
const result = await store.multipartUploadCopy(
'object',
{
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
},
{
parallel: 4,
partSize: 1024 * 1024,
progress: function (p, cpt, res) {
console.log(p);
savedCpt = cpt;
console.log(cpt);
console.log(res.headers['x-oss-request-id']);
}
}
);
console.log(result);
const result = await 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
let abortCheckpoint;
store.multipartUploadCopy('object', {
sourceKey: 'sourceKey',
sourceBucketName: 'sourceBucketName'
}, {
progress: function (p, cpt, res) {
abortCheckpoint = cpt;
}
}).then(res => {
// do something
}).catch(err => {
//if abort will catch abort event
if (err.name === 'abort') {
// handle abort
console.log('error: ', err.message)
}
});
// the other event to abort, for example: click event
// to abort upload must use the same client instance
store.abortMultipartUpload(abortCheckpoint.name, abortCheckpoint.uploadId);
//start upload
try {
const result = await 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();
const versionId = 'object versionId';
//start upload
const result = await 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']);
},
versionId
}
);
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:
const result = await 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:
const result = await 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:
const result = await store.abortMultipartUpload('object', 'upload-id');
console.log(result);
get postObject params
parameters:
Success will return postObject Api params.
Object:
Get a V4 signature of the PostObject request.
parameters:
Success will return a V4 signature of the PostObject request.
example:
const axios = require('axios');
const dateFormat = require('dateformat');
const FormData = require('form-data');
const { getCredential } = require('ali-oss/lib/common/signUtils');
const { getStandardRegion } = require('ali-oss/lib/common/utils/getStandardRegion');
const { policy2Str } = require('ali-oss/lib/common/utils/policy2Str');
const OSS = require('ali-oss');
const client = new OSS({
accessKeyId: 'yourAccessKeyId',
accessKeySecret: 'yourAccessKeySecret',
stsToken: 'yourSecurityToken',
bucket: 'yourBucket',
region: 'oss-cn-hangzhou'
});
const name = 'yourObjectName';
const formData = new FormData();
formData.append('key', name);
formData.append('Content-Type', 'yourObjectContentType');
// your object cache control
formData.append('Cache-Control', 'max-age=30');
const url = client.generateObjectUrl(name).replace(name, '');
const date = new Date();
// The expiration parameter specifies the expiration time of the request.
const expirationDate = new Date(date);
expirationDate.setMinutes(date.getMinutes() + 1);
// The time must follow the ISO 8601 standard
const formattedDate = dateFormat(date, "UTC:yyyymmdd'T'HHMMss'Z'");
const credential = getCredential(formattedDate.split('T')[0], getStandardRegion(client.options.region), client.options.accessKeyId);
formData.append('x-oss-date', formattedDate);
formData.append('x-oss-credential', credential);
formData.append('x-oss-signature-version', 'OSS4-HMAC-SHA256');
const policy = {
expiration: expirationDate.toISOString(),
conditions: [
{ bucket: client.options.bucket },
{'x-oss-credential': credential},
{'x-oss-date': formattedDate},
{'x-oss-signature-version': 'OSS4-HMAC-SHA256'},
['content-length-range', 1, 10],
['eq', '$success_action_status', '200'],
['starts-with', '$key', 'yourObjectName'],
['in', '$content-type', ['image/jpg', 'text/plain']],
['not-in', '$cache-control', ['no-cache']]
]
};
if (client.options.stsToken) {
policy.conditions.push({'x-oss-security-token': client.options.stsToken});
formData.append('x-oss-security-token', client.options.stsToken);
}
const signature = client.signPostObjectPolicyV4(policy, date);
formData.append('policy', Buffer.from(policy2Str(policy), 'utf8').toString('base64'));
formData.append('x-oss-signature', signature);
formData.append('success_action_status', '200');
formData.append('file', 'yourFileContent');
axios.post(url, formData, {
headers: {
'Content-Type': 'multipart/form-data'
}
}).then((result) => {
console.log(result.status);
}).catch((e) => {
console.log(e);
});
Obtains the tags of an object.
parameters:
Success will return the channel information.
object:
Configures or updates the tags of an object.
parameters:
{var1: value1,var2:value2}Success will return the channel information.
object:
Deletes the tag of a specified object.
parameters:
{var1: value1,var2:value2}Success will return the channel information.
object:
Persistency indicates that images are asynchronously stored in the specified Bucket
parameters:
Success will return the channel information.
object:
const sourceObject = 'a.png';
const targetObject = 'b.png';
const process = 'image/watermark,text_aGVsbG8g5Zu+54mH5pyN5Yqh77yB,color_ff6a00';
await this.store.processObjectSave(sourceObject, targetObject, process);
All operations function is [async], except getRtmpUrl.
async function format: async functionName(...).
Create a live channel.
parameters:
Success will return the channel information.
object:
example:
const cid = 'my-channel';
const conf = {
Description: 'this is channel 1',
Status: 'enabled',
Target: {
Type: 'HLS',
FragDuration: '10',
FragCount: '5',
PlaylistName: 'playlist.m3u8'
}
};
const r = await this.store.putChannel(cid, conf);
console.log(r);
Get live channel info.
parameters:
Success will return the channel information.
object:
example:
const cid = 'my-channel';
const r = await this.store.getChannel(cid);
console.log(r);
Delete a live channel.
parameters:
Success will return the response infomation.
object:
example:
const cid = 'my-channel';
const r = await this.store.deleteChannel(cid);
console.log(r);
Change the live channel status.
parameters:
Success will return the response information.
object:
example:
const cid = 'my-channel';
const r = await this.store.putChannelStatus(cid, 'disabled');
console.log(r);
Get the live channel status.
parameters:
Success will return the channel status information.
object:
example:
const cid = 'my-channel';
const r = await 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:
const r = await 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:
const cid = 'my-channel';
const r = await this.store.getChannelHistory(cid);
console.log(r);
Create a VOD playlist for the channel.
parameters:
Success will return the response information.
object:
example:
const cid = 'my-channel';
const r = await 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:
const cid = 'my-channel';
const 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:
const oss = require('ali-oss');
const imgClient = oss.ImageClient({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
bucket: 'my_image_bucket',
imageHost: 'thumbnail.myimageservice.com'
});
All operations function is [async], except imgClient.signatureUrl.
async function format: async 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:
const imagepath = '/home/ossdemo/demo.jpg';
await imgClient.get('ossdemo/demo.jpg@200w_200h', filepath);
_ Store image to a writestream
await imgClient.get('ossdemo/demo.jpg@200w_200h', somestream);
const result = await imgClient.get('ossdemo/demo.jpg@200w_200h');
console.log(Buffer.isBuffer(result.content));
const imagepath = '/home/ossdemo/demo.jpg';
await 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:
200, stream will be null.If object not exists, will throw NoSuchKeyError.
example:
const result = await 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:
const result = await 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:
const result = await 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:
const result = await 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:
const result = await 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:
const url = imgClient.signatureUrl('name');
Cluster mode now only support object operations.
const Cluster = require('ali-oss').ClusterClient;
const 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()Each error return by OSS server will contains these properties:
The default timeout is 60 seconds. Please set the timeout as needed. The timeout unit is milliseconds.
client.get('example.txt', { timeout: 60000 * 2 });
client.get('example.txt', { headers: { Range: `bytes=0-${1024 * 1024 * 100}` } }); // Download the first 100MB
The network link timed out. Please check the network status. If there is no problem with the network, please reduce the partSize or increase the timeout.
const client = new OSS({ ak, sk, retryMax: 10 });
client.multipartUpload('example.txt', { timeout: 60000 * 2 });
client.multipartUpload('example.txt', { partSize: 1024 * 512 }); // partSize 512KB
| 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
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
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.