feat: add getBucketStat method (#1102)

* feat: add getBucketStat method

* chore: add return type add documentation

README.md

@@ -69,6 +69,7 @@ All operation use es7 async/await to implement. All api is async function.
  - [.useBucket(name)](#usebucketname)
  - [.deleteBucket(name[, options])](#deletebucketname-options)
  - [.getBucketInfo(name)](#getbucketinfoname)
+ - [.getBucketStat(name)](#getbucketstatname)
  - [.getBucketLocation(name)](#getbucketlocationname)
  - ACL
  - [.putBucketACL(name, acl[, options])](#putbucketaclname-acl-options)
@@ -566,6 +567,52 @@ store.getBucketInfo('helloworld').then( (res) => {
 })
 ```
 
+### .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.
+
+```js
+store.getBucketStat().then(res=>console.log(res))
+```
+
 ### .getBucketLocation(name)
 
 Get bucket location

lib/common/bucket/getBucketStat.d.ts

@@ -0,0 +1,23 @@
+declare type bucketStatRes = {
+ Storage: string;
+ ObjectCount: string;
+ MultipartUploadCount: string;
+ LiveChannelCount: string;
+ LastModifiedTime: string;
+ StandardStorage: string;
+ StandardObjectCount: string;
+ InfrequentAccessStorage: string;
+ InfrequentAccessRealStorage: string;
+ InfrequentAccessObjectCount: string;
+ ArchiveStorage: string;
+ ArchiveRealStorage: string;
+ ArchiveObjectCount: string;
+ ColdArchiveStorage: string;
+ ColdArchiveRealStorage: string;
+ ColdArchiveObjectCount: string;
+};
+export declare function getBucketStat(this: any, name: string, options: {}): Promise<{
+ res: any;
+ stat: bucketStatRes;
+}>;
+export {};

lib/common/bucket/getBucketStat.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBucketStat = void 0;
+const checkBucketName_1 = require("../utils/checkBucketName");
+async function getBucketStat(name, options) {
+ name = name || this.options.bucket;
+ checkBucketName_1.checkBucketName(name);
+ const params = this._bucketRequestParams('GET', name, 'stat', options);
+ params.successStatuses = [200];
+ params.xmlResponse = true;
+ const result = await this.request(params);
+ return {
+ res: result.res,
+ stat: result.data
+ };
+}
+exports.getBucketStat = getBucketStat;

lib/common/bucket/getBucketStat.ts

@@ -0,0 +1,34 @@
+import { checkBucketName } from '../utils/checkBucketName';
+
+type bucketStatRes = {
+ Storage: string;
+ ObjectCount: string;
+ MultipartUploadCount: string;
+ LiveChannelCount: string;
+ LastModifiedTime: string;
+ StandardStorage: string;
+ StandardObjectCount: string;
+ InfrequentAccessStorage: string;
+ InfrequentAccessRealStorage: string;
+ InfrequentAccessObjectCount: string;
+ ArchiveStorage: string;
+ ArchiveRealStorage: string;
+ ArchiveObjectCount: string;
+ ColdArchiveStorage: string;
+ ColdArchiveRealStorage: string;
+ ColdArchiveObjectCount: string;
+};
+
+export async function getBucketStat(this: any, name: string, options: {}): Promise<{ res: any; stat: bucketStatRes }> {
+ name = name || this.options.bucket;
+ checkBucketName(name);
+ const params = this._bucketRequestParams('GET', name, 'stat', options);
+ params.successStatuses = [200];
+ params.xmlResponse = true;
+ const result = await this.request(params);
+
+ return {
+ res: result.res,
+ stat: result.data
+ };
+}

lib/common/bucket/index.js

@@ -31,3 +31,4 @@ merge(proto, require('./completeBucketWorm'));
 merge(proto, require('./extendBucketWorm'));
 merge(proto, require('./getBucketWorm'));
 merge(proto, require('./initiateBucketWorm'));
+merge(proto, require('./getBucketStat'));

test/node/bucket.test.js

@@ -1488,5 +1488,12 @@ describe('test/bucket.test.js', () => {
  }
  });
  });
+ describe('getBucketStat', () => {
+ it('should get bucket stat', async () => {
+ const result = await store.getBucketStat(bucket);
+ assert.equal(typeof result.stat, 'object');
+ assert.equal(result.res.status, 200);
+ });
+ });
  });
 });