oss-js-sdk

aliyun OSS(Object Storage Service) js client for Node and Browser env.

NOTE： For SDK 5.X document, please go to 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

You can join DingDing Talk Group, Group Link

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
Browser Usage
Data Regions
Create Account
Create A Bucket Instance
- oss(options)
Bucket Operations
Object Operations
RTMP Operations
Create A Image Service Instance
- oss.ImageClient(options)
Image Operations
Known Errors

Node Usage

Compatibility

Node: >= 8.0.0

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 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.
<!-- Introducing online resources -->
<script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
<!-- Introducing offline resources -->
<script src="https://github.com/ali-sdk/ali-oss/raw/master/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.

How to build

npm run build-dist

And see the build artifacts under dist/.

Data Regions

OSS current data regions.

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

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.

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

Global accelerate endpoint: oss-accelerate.aliyuncs.com
Accelerate endpoint of regions outside mainland China: oss-accelerate-overseas.aliyuncs.com

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; // break if success
  } 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: {
      // 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);
}

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:

List top 10 buckets

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 => {
  // use it by default
  store.useBucket('helloworld');
});

Create a bucket name helloworld location on HongKong StorageClass Archive

await store.putBucket('helloworld', { StorageClass: 'Archive' });
// use it by default
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:

stat {Object} container for the BucketStat structure:
- Storage {String} the total storage capacity of the Bucket, in bytes.
- ObjectCount {String} total number of Objects in the Bucket。
- MultipartUploadCount {String} the number of Multipart Uploads in the Bucket that have been initialized but not yet completed (Complete) or not yet aborted (Abort).
- LiveChannelCount {String} the number of Live Channels in the Bucket.
- LastModifiedTime {String} the point in time, in timestamps, when the storage information was retrieved.
- StandardStorage {String} the amount of storage of the standard storage type, in bytes.
- StandardObjectCount {String} the number of objects of the standard storage type.
- InfrequentAccessStorage {String} the amount of billed storage for the low-frequency storage type, in bytes.
- InfrequentAccessRealStorage {String} the actual storage amount of the low-frequency storage type, in bytes.
- InfrequentAccessObjectCount {String} the number of Objects of the low-frequency storage type.
- ArchiveStorage {String} the amount of billed storage for the archive storage type, in bytes.
- ArchiveRealStorage {String} the actual storage amount of the archive storage type, in bytes.
- ArchiveObjectCount {String} the number of objects of the archive storage type.
- ColdArchiveStorage {String} the amount of billed storage for the cold archive storage type, in bytes.
- ColdArchiveRealStorage {String} the actual storage amount in bytes for the cold archive storage type.
- ColdArchiveObjectCount {String} the number of objects of the cold archive storage type.
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:

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:

Get bucket helloworld

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
- data {Buffer} xml

.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

.putBucketTags(name, tag[, options])

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

.getBucketTags(name[, options])

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

.deleteBucketTags(name[, options])

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, // `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();

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;
  // list all inventory of the bucket
  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
- url {String} After a file is uploaded successfully, the OSS sends a callback request to this URL.
- [host] {String} The host header value for initiating callback requests.
- body {String} The value of the request body when a callback is initiated, for example, key=${key}&etag=${etag}&my_var=${x:my_var}.
- [contentType] {String} The Content-Type of the callback requests initiatiated, It supports application/x-www-form-urlencoded and application/json, and the former is the default value.
- [callbackSNI] {Boolean} Specifies whether OSS sends Server Name Indication (SNI) to the origin address specified by callbackUrl when a callback request is initiated from the client.
- [customValue] {Object} Custom parameters are a map of key-values
  e.g.:
```
var customValue = { var1: 'value1', var2: 'value2' };
```
- [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);
});

// {
//   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
//   }
// }

Add an object through content buffer

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
//   }
// }

Add an object through readstream

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
//   }
// }

.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
- url {String} After a file is uploaded successfully, the OSS sends a callback request to this URL.
- [host] {String} The host header value for initiating callback requests.
- body {String} The value of the request body when a callback is initiated, for example, key=${key}&etag=${etag}&my_var=${x:my_var}.
- [contentType] {String} The Content-Type of the callback requests initiatiated, It supports application/x-www-form-urlencoded and application/json, and the former is the default value.
- [callbackSNI] {Boolean} Specifies whether OSS sends Server Name Indication (SNI) to the origin address specified by callbackUrl when a callback request is initiated from the client.
- [customValue] {Object} Custom parameters are a map of key-values
  e.g.:
```
var customValue = { var1: 'value1', var2: 'value2' };
```
- [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);
});

// {
//   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(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'));

// append content to the existing object
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');
// cdnUrl should be `https://mycdn.domian.com/foo/bar.jpg`

.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');
// 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(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);

// {
//   status: 200,
//   meta: {
//     uid: '1',
//     path: 'foo/demo.txt'
//   },
//   res: { ... }
// }

Head a not exists object

const object = await this.store.head('ossdemo/head-meta');
// will throw NoSuchKeyError

.getObjectMeta(name[, options])

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);

// {
//   status: 200,
//   res: { ... }
// }

.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' });

Get a not exists object

const filepath = '/home/ossdemo/demo.txt';
await store.get('ossdemo/not-exists-demo.txt', filepath);
// will throw NoSuchKeyError

Get a historic version object

const filepath = '/home/ossdemo/demo.txt';
const versionId = 'versionId string';
await store.get('ossdemo/not-exists-demo.txt', filepath, {
  versionId
});

If file is Object, it will be treated as options.

const versionId = 'versionId string';
await store.get('ossdemo/not-exists-demo.txt', { versionId });

.getStream(name[, options])

Get an object read stream.

parameters:

name {String} object name store on OSS
[options] {Object} optional parameters
- [timeout] {Number} the operation timeout
- [process] {String} image process params, will send with x-oss-process
- [headers] {Object} extra headers
- '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 stream instance and response info.

object:

stream {ReadStream} readable stream instance. If response status is not 200, stream will be 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)

If object not exists, will throw NoSuchKeyError.

example:

Get an exists object stream

const result = await store.getStream('ossdemo/demo.txt');
result.stream.pipe(fs.createWriteStream('some file.txt'));

.delete(name[, options])

Delete an object from the bucket.

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 info contains response.

object:

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 delete object not exists, will also delete success.

example:

Delete an exists object

await store.delete('ossdemo/someobject');

Delete a not exists object

await store.delete('ossdemo/some-not-exists-object');

Delete a history object or deleteMarker

const versionId = 'versionId';
await store.delete('ossdemo/some-not-exists-object', { versionId });

.copy(name, sourceName[, sourceBucket, options])

Copy an object from sourceName to name.

parameters:

name {String} object name store on OSS
sourceName {String} source object name
[sourceBucket] {String} source Bucket. if doesn't exist，sourceBucket is same bucket.
[options] {Object} optional parameters
- [versionId] {String} the version id of history object
- [timeout] {Number} the operation timeout
- [meta] {Object} user meta, will send with x-oss-meta- prefix string e.g.: { uid: 123, pid: 110 } If the meta set, will override the source object meta.
- [headers] {Object} extra headers
- 'If-Match' do copy if source object etag equal this, otherwise throw PreconditionFailedError
- 'If-None-Match' do copy if source object etag not equal this, otherwise throw PreconditionFailedError
- 'If-Modified-Since' do copy if source object modified after this time, otherwise throw PreconditionFailedError
- 'If-Unmodified-Since' do copy if source object modified before this time, otherwise throw PreconditionFailedError
- See more: CopyObject

Success will return the copy result in data property.

object:

data {Object} copy result
- lastModified {String} object last modified GMT string
- etag {String} object etag contains ", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"
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 source object not exists, will throw NoSuchKeyError.

example:

Copy same bucket object

store.copy('newName', 'oldName').then(result => {
  console.log(result);
});

Copy other bucket object

store.copy('logo.png', 'logo.png', 'other-bucket').then(result => {
  console.log(result);
});

Copy historic object

const versionId = 'your verisonId';
store.copy('logo.png', 'logo.png', 'other-bucket', { versionId }).then(result => {
  console.log(result);
});

.putMeta(name, meta[, options])

Set an exists object meta.

parameters:

name {String} object name store on OSS
meta {Object} user meta, will send with x-oss-meta- prefix string e.g.: { uid: 123, pid: 110 } If meta: null, will clean up the exists meta
[options] {Object} optional parameters
- [timeout] {Number} the operation timeout

Success will return the putMeta result in data property.

data {Object} copy result
- lastModified {String} object last modified GMT date, e.g.: 2015-02-19T08:39:44.000Z
- etag {String} object etag contains ", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"
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:

Update exists object meta

const result = await store.putMeta('ossdemo.txt', {
  uid: 1,
  pid: 'p123'
});
console.log(result);

Clean up object meta

await store.putMeta('ossdemo.txt', null);

.deleteMulti(names[, options])

Delete multi objects in one request.

parameters:

names {Array

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 超时失效

ali-sdk / ali-oss

readme

oss-js-sdk

Install

Compatibility

Node

Browser

QA

License

OSS Usage

Summary

Node Usage

Compatibility

Basic usage

Browser Usage

Compatibility

Setup

Bucket setup

STS setup

Basic usage

How to build

Data Regions

Create Account

Create A Bucket Instance

oss(options)

Bucket Operations

.listBuckets(query[, options])

.putBucket(name[, options])

.deleteBucket(name[, options])

.useBucket(name)

.getBucketInfo(name)

.getBucketStat(name)

.getBucketLocation(name)

.putBucketACL(name, acl[, options])

.getBucketACL(name[, options])

.putBucketLogging(name, prefix[, options])

.getBucketLogging(name[, options])

.deleteBucketLogging(name[, options])

.putBucketWebsite(name, config[, options])

.getBucketWebsite(name[, options])

.deleteBucketWebsite(name[, options])

.putBucketReferer(name, allowEmpty, referers[, options])

.getBucketReferer(name[, options])

.deleteBucketReferer(name[, options])

.putBucketLifecycle(name, rules[, options])

.getBucketLifecycle(name[, options])

.deleteBucketLifecycle(name[, options])

.putBucketCORS(name, rules[, options])

.getBucketCORS(name[, options])

.deleteBucketCORS(name[, options])

.getBucketRequestPayment(bucketName[, options])

.putBucketRequestPayment(bucketName, payer[, options])

.putBucketEncryption(name, rules)

.getBucketEncryption(name)

.deleteBucketEncryption(name)

.putBucketTags(name, tag[, options])

.getBucketTags(name[, options])

.deleteBucketTags(name[, options])

.putBucketPolicy(name, policy[, options])

.getBucketPolicy(name[, options])

.deleteBucketPolicy(name[, options])

.getBucketVersioning(name[, options])

.putBucketVersioning(name, status[, options])

.getBucketInventory(name, inventoryId[, options])

putBucketInventory(name, inventory[, options])

deleteBucketInventory(name, inventoryId[, options])

listBucketInventory(name[, options])

.abortBucketWorm(name[, options])

.completeBucketWorm(name, wormId[, options])

.extendBucketWorm(name, wormId, days[, options])

.getBucketWorm(name[, options])

.initiateBucketWorm(name, days[, options])

Object Operations

.put(name, file[, options])

.putStream(name, stream[, options])

.append(name, file[, options])

.getObjectUrl(name[, baseUrl])

.generateObjectUrl(name[, baseUrl])

.head(name[, options])

.getObjectMeta(name[, options])