oss-js-sdk
aliyun OSS(Object Storage Service) js client for Node and Browser env.
NOTE： For SDK 5.X document, please go to 5.X README.md
Install
npm install ali-oss --save
Compatibility
Node
Node.js >= 8.0.0 required. You can use 4.x in Node.js < 8.
Browser
- IE >= 10 & Edge
- Major versions of Chrome/Firefox/Safari
- Major versions of Android/iOS/WP
Note:
- For Lower browsers you can refer to PostObject, if you want to see more practices ,please refer to Web Post
QA
Please log in to the official website and contact technical support.
License
MIT
OSS Usage
OSS, Object Storage Service. Equal to well known Amazon S3.
All operation use es7 async/await to implement. All api is async function.
Summary
Node Usage
Compatibility
Basic usage
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>'
});
Browser Usage
You can use most of the functionalities of ali-oss in browser with
some exceptions:
- put object with streaming: no chunked encoding, we use multipart
upload instead
- get object to local file: we cannot manipulate file system in
browser, we provide signed object url for downloading needs
- bucket operations(listBuckets, putBucketLogging, etc) will fail: OSS
server currently do not support CORS requests for bucket operations
(will probably be fixed later)
Compatibility
- IE >= 10 & Edge
- Major versions of Chrome/Firefox/Safari
- Major versions of Android/iOS/WP
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.
Setup
Bucket setup
As browser-side javascript involves CORS operations. You need to setup
your bucket CORS rules to allow CORS operations:
- set allowed origins to ‘*’
- allowed methods to ‘PUT, GET, POST, DELETE, HEAD’
- set allowed headers to ‘*’
- expose ‘ETag’ in expose headers
STS setup
As we don’t want to expose the accessKeyId/accessKeySecret in the
browser, a [common practice][oss-sts] is to use STS to grant temporary
access.
Basic usage
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.
<script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
<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][browser-sample].
How to build
npm run build-dist
And see the build artifacts under dist/.
Data Regions
OSS current data regions.
Create Account
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.
Create A Bucket Instance
Each OSS instance required accessKeyId, accessKeySecret and bucket.
oss(options)
Create a Bucket store instance.
options:
- accessKeyId {String} access key you create on aliyun console website
- accessKeySecret {String} access secret you create
- [stsToken] {String} used by temporary authorization, detail see
- [refreshSTSToken] {Function} used by auto set
stsToken、accessKeyId、accessKeySecret when sts info expires. return value must be object contains stsToken、accessKeyId、accessKeySecret
- [refreshSTSTokenInterval] {number} use time (ms) of refresh STSToken interval it should be less than sts info expire interval, default is 300000ms(5min)
- [bucket] {String} the default bucket you want to access
If you don’t have any bucket, please use
putBucket() create one first.
- [endpoint] {String} oss region domain. It takes priority over
region. Set as extranet domain name, intranet domain name, accelerated domain name, etc. according to different needs. please see endpoints
- [region] {String} the bucket data region location, please see Data Regions,
default is
oss-cn-hangzhou.
- [internal] {Boolean} access OSS with aliyun internal network or not, default is
false.
If your servers are running on aliyun too, you can set true to save a lot of money.
- [secure] {Boolean} instruct OSS client to use HTTPS (secure: true) or HTTP (secure: false) protocol.
- [timeout] {String|Number} instance level timeout for all operations, default is
60s.
- [cname] {Boolean}, default false, access oss with custom domain name. if true, you can fill
endpoint field with your custom domain name,
- [isRequestPay] {Boolean}, default false, whether request payer function of the bucket is open, if true, will send headers
'x-oss-request-payer': 'requester' to oss server.
the details you can see requestPay
- [useFetch] {Boolean}, default false, it just work in Browser, if true,it means upload object with
fetch mode ,else XMLHttpRequest
- [enableProxy] {Boolean}, Enable proxy request, default is false. NOTE: When enabling proxy request, please ensure that proxy-agent is installed.
- [proxy] {String | Object}, proxy agent uri or options, default is null.
- [retryMax] {Number}, used by auto retry send request count when request error is net error or timeout. NOTE: Not support
put with stream, putStream, append with stream because the stream can only be consumed once
- [maxSockets] {Number} Maximum number of sockets to allow per host. Default is infinity
- [authorizationV4] {Boolean} Use V4 signature. Default is false.
- [cloudBoxId] {String} the CloudBox ID you want to access. When configuring this option, please set the endpoint option to the CloudBox endpoint and set the authorizationV4 option to true.
example:
- basic usage
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'
});
- use accelerate endpoint
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'
});
- use custom domain
const OSS = require('ali-oss');
const store = new OSS({
accessKeyId: 'your access key',
accessKeySecret: 'your access secret',
cname: true,
endpoint: 'your custome domain'
});
- use STS and refreshSTSToken
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
});
- retry request with stream
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;
} catch (e) {
console.log(e);
}
}
- use V4 signature, and use optional additionalHeaders option which type is a string array, and the values inside need to be included in the header.
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: {
header1: 'value1',
header2: 'value2'
},
additionalHeaders: ['additional header1', 'additional header2']
});
console.log(putObjectResult);
} catch (e) {
console.log(e);
}
Bucket Operations
.listBuckets(query[, options])
List buckets in this account.
parameters:
- [query] {Object} query parameters, default is
null
- [prefix] {String} search buckets using
prefix key
- [marker] {String} search start from
marker, including marker key
- [max-keys] {String|Number} max buckets, default is
100, limit to 1000
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return buckets list on buckets properties.
- buckets {Array} bucket meta info list
Each
BucketMeta will contains blow properties:
- name {String} bucket name
- region {String} bucket store data region, e.g.:
oss-cn-hangzhou-a
- creationDate {String} bucket create GMT date, e.g.:
2015-02-19T08:39:44.000Z
- storageClass {String} e.g.:
Standard, IA, Archive
- owner {Object} object owner, including
id and displayName
- isTruncated {Boolean} truncate or not
- nextMarker {String} next marker string
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
store
.listBuckets({
'max-keys': 10
})
.then(result => {
console.log(result);
});
.putBucket(name[, options])
Create a new bucket.
parameters:
- name {String} bucket name
If bucket exists and not belong to current account, will throw BucketAlreadyExistsError.
If bucket not exists, will create a new bucket and set it’s ACL.
- [options] {Object} optional parameters
- [acl] {String} include
private,public-read,public-read-write
- [storageClass] {String} the storage type include (Standard,IA,Archive)
- [dataRedundancyType] {String} default
LRS, include LRS,ZRS
- [timeout] {Number} the operation timeout
Success will return the bucket name on bucket properties.
- bucket {String} bucket name
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Create a bucket name
helloworld location on HongKong
store.putBucket('helloworld').then(result => {
store.useBucket('helloworld');
});
- Create a bucket name
helloworld location on HongKong StorageClass Archive
await store.putBucket('helloworld', { StorageClass: 'Archive' });
store.useBucket('helloworld');
.deleteBucket(name[, options])
Delete an empty bucket.
parameters:
- name {String} bucket name
If bucket is not empty, will throw BucketNotEmptyError.
If bucket is not exists, will throw NoSuchBucketError.
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Delete the exists ‘helloworld’ bucket on ‘oss-cn-hongkong’
store.deleteBucket('helloworld').then(result => {});
.useBucket(name)
Use the bucket.
parameters:
- name {String} bucket name
example:
- Use
helloworld as the default bucket
store.useBucket('helloworld');
.getBucketInfo(name)
Get bucket information,include CreationDate、ExtranetEndpoint、IntranetEndpoint、Location、Name、StorageClass、
Owner、AccessControlList、Versioning
parameters:
- name {String} bucket name
example:
- Use
helloworld as the default bucket
store.getBucketInfo('helloworld').then(res => {
console.log(res.bucket);
});
.getBucketStat(name)
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:
- name {String} bucket name
Success will return:
example:
- If you don’t fill in the name, the default is the bucket defined during initialization.
store.getBucketStat().then(res => console.log(res));
.getBucketLocation(name)
Get bucket location
parameters:
- name {String} bucket name
example:
- Use
helloworld as the default bucket
store.getBucketLocation('helloworld').then(res => {
console.log(res.location);
});
.putBucketACL(name, acl[, options])
Update the bucket ACL.
parameters:
- name {String} bucket name
- acl {String} access control list, current available:
public-read-write, public-read and private
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Set bucket
helloworld to public-read-write
store.putBucketACL('helloworld', 'public-read-write').then(result => {});
.getBucketACL(name[, options])
Get the bucket ACL.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- acl {String} acl settiongs string
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
store.getBucketACL('helloworld').then(result => {
console.log(result.acl);
});
.putBucketLogging(name, prefix[, options])
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:
- name {String} bucket name
- [prefix] {String} prefix path name to store the log files
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Enable bucket
helloworld logging and save with prefix logs/
store.putBucketLogging('helloworld', 'logs/').then(result => {});
.getBucketLogging(name[, options])
Get the bucket logging settings.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- enable {Boolean} enable logging or not
- prefix {String} prefix path name to store the log files, maybe
null
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Get bucket
helloworld logging settings
store.getBucketLogging('helloworld').then(result => {
console.log(result.enable, result.prefix);
});
.deleteBucketLogging(name[, options])
Delete the bucket logging settings.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.putBucketWebsite(name, config[, options])
Set the bucket as a static website.
parameters:
- name {String} bucket name
- config {Object} website config, contains blow properties:
- index {String} default page, e.g.:
index.html
- [error] {String} error page, e.g.: ‘error.html’
- [supportSubDir] {String} default vaule false
- [type] {String} default value 0
- [routingRules] {Array} RoutingRules
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
store
.putBucketWebsite('hello', {
index: 'index.html'
})
.then(result => {});
.getBucketWebsite(name[, options])
Get the bucket website config.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- index {String} index page
- error {String} error page, maybe
null
- supportSubDir {String}
- type {String}
- routingRules {Array}
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.deleteBucketWebsite(name[, options])
Delete the bucket website config.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.putBucketReferer(name, allowEmpty, referers[, options])
Set the bucket request Referer white list.
parameters:
- name {String} bucket name
- allowEmpty {Boolean} allow empty request referer or not
- referers {Array}
Referer white list, e.g.:['https://npm.taobao.org', 'http://cnpmjs.org'];
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
store.putBucketReferer('hello', false, ['https://npm.taobao.org', 'http://cnpmjs.org']).then(result => {});
.getBucketReferer(name[, options])
Get the bucket request Referer white list.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- allowEmpty {Boolean} allow empty request referer or not
- referers {Array}
Referer white list
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.deleteBucketReferer(name[, options])
Delete the bucket request Referer white list.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.putBucketLifecycle(name, rules[, options])
Set the bucket object lifecycle.
parameters:
- name {String} bucket name
- rules {Array} rule config list, each
Rule will contains blow properties:
- [id] {String} rule id, if not set, OSS will auto create it with random string.
- prefix {String} store prefix
- status {String} rule status, allow values:
Enabled or Disabled
- [expiration] {Object} specifies the expiration attribute of the lifecycle rules for the object.
- [days] {Number|String} expire after the
days
- [createdBeforeDate] {String} expire date, e.g.:
2022-10-11T00:00:00.000Z
- [expiredObjectDeleteMarker] {String} value
true
createdBeforeDate and days and expiredObjectDeleteMarker must have one.
- [abortMultipartUpload] {Object} Specifies the expiration attribute of the multipart upload tasks that are not complete.
- [days] {Number|String} expire after the
days
- [createdBeforeDate] {String} expire date, e.g.:
2022-10-11T00:00:00.000Z
createdBeforeDate and days must have one.
- [transition] {Object} Specifies the time when an object is converted to the IA or archive storage class during a valid life cycle.
- storageClass {String} Specifies the storage class that objects that conform to the rule are converted into. allow values:
IA or Archive or ColdArchive or DeepColdArchive
- [days] {Number|String} expire after the
days
- [createdBeforeDate] {String} expire date, e.g.:
2022-10-11T00:00:00.000Z
createdBeforeDate and days must have one.
- [noncurrentVersionTransition] {Object} Specifies the time when an object is converted to the IA or archive storage class during a valid life cycle.
- storageClass {String} Specifies the storage class that history objects that conform to the rule are converted into. allow values:
IA or Archive or ColdArchive or DeepColdArchive
- noncurrentDays {String} expire after the
noncurrentDays
expiration、 abortMultipartUpload、 transition、 noncurrentVersionTransition must have one.
- [noncurrentVersionExpiration] {Object} specifies the expiration attribute of the lifecycle rules for the history object.
- noncurrentDays {String} expire after the
noncurrentDays
- [tag] {Object} Specifies the object tag applicable to a rule. Multiple tags are supported.
- key {String} Indicates the tag key.
- value {String} Indicates the tag value.
tag cannot be used with abortMultipartUpload
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
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);
.getBucketLifecycle(name[, options])
Get the bucket object lifecycle.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- rules {Array} the lifecycle rule list
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.deleteBucketLifecycle(name[, options])
Delete the bucket object lifecycle.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.putBucketCORS(name, rules[, options])
Set CORS rules of the bucket object
parameters:
- name {String} bucket name
- rules {Array} rule config list, each
Rule will contains below properties:
- allowedOrigin {String/Array} configure for Access-Control-Allow-Origin header
- allowedMethod {String/Array} configure for Access-Control-Allow-Methods header
- [allowedHeader] {String/Array} configure for Access-Control-Allow-Headers header
- [exposeHeader] {String/Array} configure for Access-Control-Expose-Headers header
- [maxAgeSeconds] {String} configure for Access-Control-Max-Age header
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
store
.putBucketCORS('hello', [
{
allowedOrigin: '*',
allowedMethod: ['GET', 'HEAD']
}
])
.then(result => {});
.getBucketCORS(name[, options])
Get CORS rules of the bucket object.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- rules {Array} the CORS rule list
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.deleteBucketCORS(name[, options])
Delete CORS rules of the bucket object.
parameters:
- name {String} bucket name
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
Success will return:
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
.getBucketRequestPayment(bucketName[, options])
get RequestPayment value of the bucket object.
parameters:
- bucketName {String} bucket name
- [options] {Object} optional parameters
Success will return:
- status {Number} response status
- payer {String} payer, BucketOwner or Requester
- res {Object} response info, including
.putBucketRequestPayment(bucketName, payer[, options])
put RequestPayment value of the bucket object.
parameters:
- bucketName {String}
- payer {String} payer
- [options] {Object} optional parameters
Success will return:
- status {Number} response status
- res {Object} response info
.putBucketEncryption(name, rules)
put BucketEncryption value of the bucket object.
parameters:
- name {String} bucket name
- [rules] {Object} parameters
- SSEAlgorithm {String} encryption type, expect AES256 or KMS
- {KMSMasterKeyID} {String} needed when encryption type is KMS
Success will return:
- status {Number} response status
- res {Object} response info
.getBucketEncryption(name)
get BucketEncryption rule value of the bucket object.
parameters:
- name {String} bucket name
Success will return:
- status {Number} response status
- res {Object} response info
- encryption {Object} rules
- SSEAlgorithm {String} encryption type, AES256 or KMS
- {KMSMasterKeyID} {String} will be return when encryption type is KMS
.deleteBucketEncryption(name)
delete BucketEncryption rule value of the bucket object.
parameters:
- name {String} bucket name
Success will return:
- status {Number} response status
- res {Object} response info
Adds tags for a bucket or modify the tags for a bucket.
parameters:
- name {String} the object name
- tag {Object} tag, eg.
{var1: value1,var2:value2}
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
Obtains the tags for a bucket.
parameters:
- name {String} the object name
- [options] {Object} optional args
Success will return:
- tag {Object} the tag of object
- res {Object} response info
Deletes the tags added for a bucket.
parameters:
- name {String} the object name
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.putBucketPolicy(name, policy[, options])
Adds or modify policy for a bucket.
parameters:
- name {String} the bucket name
- policy {Object} bucket policy
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
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);
.getBucketPolicy(name[, options])
Obtains the policy for a bucket.
parameters:
- name {String} the bucket name
- [options] {Object} optional args
Success will return:
- policy {Object} the policy of bucket, if not exist, the value is null
- res {Object} response info
- status {Number} response status
.deleteBucketPolicy(name[, options])
Deletes the policy added for a bucket.
parameters:
- name {String} the bucket name
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.getBucketVersioning(name[, options])
Obtains the version status of an object
parameters:
- name {String} the bucket name
- [options] {Object} optional args
Success will return:
- status {Number} response status
- versionStatus {String | undefined} version status,
Suspended or Enabled. default value: undefined
- res {Object} response info
.putBucketVersioning(name, status[, options])
set the version status of an object
parameters:
- name {String} the bucket name
- status {String} version status, allow values:
Enabled or Suspended
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.getBucketInventory(name, inventoryId[, options])
get bucket inventory by inventory-id
parameters:
- name {String} the bucket name
- inventoryId {String} inventory-id
- [options] {Object} optional args
Success will return:
- inventory {Inventory}
- status {Number} response status
- res {Object} response info
async function getBucketInventoryById() {
try {
const result = await store.getBucketInventory('bucket', 'inventoryid');
console.log(result.inventory);
} catch (err) {
console.log(err);
}
}
getBucketInventoryById();
putBucketInventory(name, inventory[, options])
set bucket inventory
parameters:
- name {String} the bucket name
- inventory {Inventory} inventory config
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
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,
prefix: 'ttt',
OSSBucketDestination: {
format: 'CSV',
accountId: '1817184078010220',
rolename: 'AliyunOSSRole',
bucket: 'your bucket',
prefix: 'test'
},
frequency: 'Daily',
includedObjectVersions: 'All',
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();
deleteBucketInventory(name, inventoryId[, options])
delete bucket inventory by inventory-id
parameters:
- name {String} the bucket name
- inventoryId {String} inventory-id
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
listBucketInventory(name[, options])
list bucket inventory
parameters:
- name {String} the bucket name
- [options] {Object} optional args
- continuationToken used by search next page
Success will return:
- status {Number} response status
- res {Object} response info
example:
async function listBucketInventory() {
const bucket = 'Your Bucket Name';
let nextContinuationToken;
do {
const result = await store.listBucketInventory(bucket, nextContinuationToken);
console.log(result.inventoryList);
nextContinuationToken = result.nextContinuationToken;
} while (nextContinuationToken);
}
listBucketInventory();
.abortBucketWorm(name[, options])
used to delete an unlocked retention policy.
parameters:
- name {String} the bucket name
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.completeBucketWorm(name, wormId[, options])
used to lock a retention policy.
parameters:
- name {String} the bucket name
- wormId {String} worm id
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.extendBucketWorm(name, wormId, days[, options])
used to extend the retention period of objects in a bucket whose retention policy is locked.
parameters:
- name {String} the bucket name
- wormId {String} worm id
- days {String | Number} retention days
- [options] {Object} optional args
Success will return:
- status {Number} response status
- res {Object} response info
.getBucketWorm(name[, options])
used to query the retention policy information of the specified bucket.
parameters:
- name {String} the bucket name
- [options] {Object} optional args
Success will return:
- wormId {String} worm id
- state {String}
Locked or InProgress
- days {String} retention days
- creationDate {String}
- status {Number} response status
- res {Object} response info
.initiateBucketWorm(name, days[, options])
create a retention policy.
parameters:
- name {String} the bucket name
- days {String | Number}} set retention days
- [options] {Object} optional args
Success will return:
- wormId {String} worm id
- status {Number} response status
- res {Object} response info
Object Operations
All operations function return Promise, except signatureUrl.
.put(name, file[, options])
Add an object to the bucket.
parameters:
- name {String} object name store on OSS
- file {String|Buffer|ReadStream|File(only support Browser)|Blob(only support Browser)} object local path, content buffer or ReadStream content instance use in Node, Blob and html5 File
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout (ms)
- [mime] {String} custom mime, will send with
Content-Type entity header
- [meta] {Object} user meta, will send with
x-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }
- [callback] {Object} The callback parameter is composed of a JSON string encoded in Base64,detail see
- [headers] {Object} extra headers
- ‘Cache-Control’ cache control for download, e.g.:
Cache-Control: public, no-cache
- ‘Content-Disposition’ object name for download, e.g.:
Content-Disposition: somename
- ‘Content-Encoding’ object content encoding for download, e.g.:
Content-Encoding: gzip
- ‘Expires’ expires time for download, an absolute date and time. e.g.:
Tue, 08 Dec 2020 13:49:43 GMT
- See more: PutObject
- [disabledMD5] {Boolean} default true, it just work in Browser. if false,it means that MD5 is automatically calculated for uploaded files. NOTE: Synchronous computing tasks will block the main process
Success will return the object information.
object:
- name {String} object name
- data {Object} callback server response data, sdk use JSON.parse() return
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Add an object through local file path
const filepath = '/home/ossdemo/demo.txt';
store.put('ossdemo/demo.txt', filepath).then((result) => {
console.log(result);
});
- Add an object through content buffer
store.put('ossdemo/buffer', Buffer.from('foo content')).then((result) => {
console.log(result);
});
- Add an object through readstream
const filepath = '/home/ossdemo/demo.txt';
store.put('ossdemo/readstream.txt', fs.createReadStream(filepath)).then((result) => {
console.log(result);
});
.putStream(name, stream[, options])
Add a stream object to the bucket.
parameters:
- name {String} object name store on OSS
- stream {ReadStream} object ReadStream content instance
- [options] {Object} optional parameters
- [contentLength] {Number} the stream length,
chunked encoding will be used if absent
- [timeout] {Number} the operation timeout
- [mime] {String} custom mime, will send with
Content-Type entity header
- [meta] {Object} user meta, will send with
x-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }
- [callback] {Object} The callback parameter is composed of a JSON string encoded in Base64,detail see
- [headers] {Object} extra headers, detail see RFC 2616
- ‘Cache-Control’ cache control for download, e.g.:
Cache-Control: public, no-cache
- ‘Content-Disposition’ object name for download, e.g.:
Content-Disposition: somename
- ‘Content-Encoding’ object content encoding for download, e.g.:
Content-Encoding: gzip
- ‘Expires’ expires time for download, an absolute date and time. e.g.:
Tue, 08 Dec 2020 13:49:43 GMT
Success will return the object information.
object:
- name {String} object name
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Add an object through readstream
const filepath = '/home/ossdemo/demo.txt';
store.putStream('ossdemo/readstream.txt', fs.createReadStream(filepath)).then((result) => {
console.log(result);
});
.append(name, file[, options])
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
- name {String} object name store on OSS
- file {String|Buffer|ReadStream} object local path, content buffer or ReadStream content instance
- [options] {Object} optional parameters
- [position] {String} specify the position which is the content length of the latest object
- [timeout] {Number} the operation timeout
- [mime] {String} custom mime, will send with
Content-Type entity header
- [meta] {Object} user meta, will send with
x-oss-meta- prefix string
e.g.: { uid: 123, pid: 110 }
- [headers] {Object} extra headers, detail see RFC 2616
- ‘Cache-Control’ cache control for download, e.g.:
Cache-Control: public, no-cache
- ‘Content-Disposition’ object name for download, e.g.:
Content-Disposition: somename
- ‘Content-Encoding’ object content encoding for download, e.g.:
Content-Encoding: gzip
- ‘Expires’ expires time for download, an absolute date and time. e.g.:
Tue, 08 Dec 2020 13:49:43 GMT
object:
- name {String} object name
- url {String} the url of oss
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
- nextAppendPosition {String} the next position（The browser needs to set cross domain and expose the x-oss-next-append-position header）
example:
let object = await store.append('ossdemo/buffer', Buffer.from('foo'));
object = await store.append('ossdemo/buffer', Buffer.from('bar'), {
position: object.nextAppendPosition
});
.getObjectUrl(name[, baseUrl])
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');
.generateObjectUrl(name[, baseUrl])
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');
const cdnUrl = store.generateObjectUrl('foo/bar.jpg', 'https://mycdn.domian.com');
.head(name[, options])
Head an object and get the meta info.
parameters:
- name {String} object name store on OSS
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
- [versionId] {String} the version id of history object
- [headers] {Object} extra headers, detail see RFC 2616
- ‘If-Modified-Since’ object modified after this time will return 200 and object meta,
otherwise return 304 not modified
- ‘If-Unmodified-Since’ object modified before this time will return 200 and object meta,
otherwise throw PreconditionFailedError
- ‘If-Match’ object etag equal this will return 200 and object meta,
otherwise throw PreconditionFailedError
- ‘If-None-Match’ object etag not equal this will return 200 and object meta,
otherwise return 304 not modified
Success will return the object’s meta information.
object:
- status {Number} response status, maybe 200 or 304
- meta {Object} object user meta, if not set on
put(), will return null.
If return status 304, meta will be null too
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- [x-oss-version-id] return in multiversion
- size {Number} response size
- rt {Number} request total use time (ms)
example:
- Head an exists object and get user meta
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);
const object = await this.store.head('ossdemo/head-meta');
Get an object meta info include ETag、Size、LastModified and so on, not return object content.
parameters:
- name {String} object name store on OSS
- [options] {Object} optional parameters
- [timeout] {Number} the operation timeout
- [versionId] {String} the version id of history object
Success will return the object’s meta information.
object:
- status {Number} response status
- res {Object} response info, including
- headers {Object} response headers
example:
- Head an exists object and get object meta info
await this.store.put('ossdemo/object-meta', Buffer.from('foo'));
const object = await this.store.getObjectMeta('ossdemo/object-meta');
console.log(object);
.get(name[, file, options])
Get an object from the bucket.
parameters:
- name {String} object name store on OSS
- [file] {String|WriteStream|Object} file path or WriteStream instance to store the content
If
file is null or ignore this parameter, function will return info contains content property.
If file is Object, it will be treated as options.
- [options] {Object} optional parameters
- [versionId] {String} the version id of history object
- [timeout] {Number} the operation timeout
- [process] {String} image process params, will send with
x-oss-process
e.g.: {process: 'image/resize,w_200'}
- [responseCacheControl] {String} default
no-cache, (only support Browser). response-cache-control, will response with HTTP Header Cache-Control
- [headers] {Object} extra headers, detail see RFC 2616
- ‘Range’ get specifying range bytes content, e.g.:
Range: bytes=0-9
- ‘If-Modified-Since’ object modified after this time will return 200 and object meta,
otherwise return 304 not modified
- ‘If-Unmodified-Since’ object modified before this time will return 200 and object meta,
otherwise throw PreconditionFailedError
- ‘If-Match’ object etag equal this will return 200 and object meta,
otherwise throw PreconditionFailedError
- ‘If-None-Match’ object etag not equal this will return 200 and object meta,
otherwise return 304 not modified
Success will return the info contains response.
object:
- [content] {Buffer} file content buffer if
file parameter is null or ignore
- res {Object} response info, including
- status {Number} response status
- headers {Object} response headers
- size {Number} response size
- rt {Number} request total use time (ms)
If object not exists, will throw NoSuchKeyError.
example:
- Get an exists object and store it to the local file
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);
- Get an object content buffer
const result = await store.get('ossdemo/demo.txt');
console.log(Buffer.isBuffer(result.content));
- Get a processed image and store it to the local file
const filepath = '/home/ossdemo/demo.png';
await store.get('ossdemo/demo.png', filepath, { process: 'image/resize,w_200' });
README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。
评论