A bucket may have a lot of objects. The SDK provides a series of interfaces for you to conveniently manage the objects.

View all objects

The following code uses ‘list’ to list all objects in the current bucket. Main parameters are described as follows:

• prefix: Specify to only list objects with specific prefixes.
• marker: Specify to list objects whose names are greater than a specified marker.
• delimiter: Obtain the common prefix of a group of objects
• max-keys: Specify the maximum number of objects returned

var co = require('co');
var OSS = require('ali-oss');
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  // Without any parameters. A maximum of 1,000 objects can be returned by default. 
  var result = yield client.list();
  console.log(result);
  // Continue to list objects based on nextMarker
  if (result.isTruncated) {
    var result = yield client.list({
      marker: result.nextMarker
    });
  }
  // List all objects whose names contain the "my-" prefix
  var result = yield client.list({
    prefix: 'my-'
  });
  console.log(result);
  // List all objects whose names are greater than "my-object" marker and contain the "my-" prefix
  var result = yield client.list({
    prefix: 'my-',
    marker: 'my-object'
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Simulate the directory structure

OSS is an object-based storage service. It has no directory. All objects stored in a bucket are uniquely identified by the key of the object. There is no hierarchical structure among these objects. Such a structure allows OSS to efficiently store objects.

However, you may want to put different types of objects under different “directories” to manage objects in a conventional way. OSS provides a “Public Prefix” feature for you to conveniently create a stimulated directory structure. For more information about the public prefix concept, refer to List Object.

Suppose that the bucket already contains the following objects:

foo/x
foo/y
foo/bar/a
foo/bar/b
foo/hello/C/1
foo/hello/C/2
...
foo/hello/C/9999

Next we will implement a function called ‘listDir’ to list all the objects and subdirectories under the specified directory:

var co = require('co');
var OSS = require('ali-oss');
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
function* listDir(dir)
  var result = yield client.list({
    prefix: dir,
    delimiter: '/'
  });
  result.prefixes.forEach(function (subDir) {
    console.log('SubDir: %s', subDir);
  });
  result.objects.forEach(function (obj) {
    console.log(Object: %s', obj.name);
  });
end

The execution results are as follows:

> yield listDir('foo/')
=> SubDir: foo/bar/
   SubDir: foo/hello/
   Object: foo/x
   Object: foo/y
> yield listDir('foo/bar/')
=> Object: foo/bar/a
   Object: foo/bar/b
> yield listDir('foo/hello/C/')
=> Object: foo/hello/C/1
   Object: foo/hello/C/2
   ...
   Object: foo/hello/C/9999

Object metadata

When uploading an object to OSS, except for the object content, you can specify certain attribute information for the object. The attribute information is called meta information.

The metadata is stored together with the object during uploading, and returned together with the object during downloading.

Because the object meta information is stored in HTTP headers during object uploading/downloading, the meta information cannot contain any complex characters according to HTTP. Therefore, the meta information should only contain simple printable ASCII characters and cannot contain line breaks. The maximum size of all meta information cannot exceed 8KB.

You can specify the object meta information by specifying the ‘meta’ parameter when using the ‘put’, ‘putStream’ and ‘multipartUpload’:

var co = require('co');
var OSS = require('ali-oss')
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  var result = yield client.put('object-key', 'local-file', {
    meta: {
      year: 2016,
      people: 'mary'
    }
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Update the object meta information through the ‘putMeta’ interface:

var co = require('co');
var OSS = require('ali-oss')
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  var result = yield client.putMeta('object-key', {
    meta: {
      year: 2015,
      people: 'mary'
    }
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Copy an object

Copy an object using ‘copy’. The copy may fall under the following two types of scenarios:

• The same bucket
• Two different buckets in the region. In this case, the source object name should be in the format of‘/bucket/object’.

In addition, when an object is copied, there are two methods for processing the object metadata:

• If no ‘meta’ parameter is specified, the metadata remains the same as that of the source object, that is, copying the source object metadata
• If the ‘meta’ parameter is specified, overwrite the source object information with the new metadata

var co = require('co');
var OSS = require('ali-oss')
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  // Copying between two buckets
  var result = yield client.copy('to', '/from-bucket/from');
  console.log(result);
  // Copy the meta information
  var result = yield client.copy('to', 'from');
  console.log(result);
  // Overwrite the meta information
  var result = yield client.copy('to', 'from', {
    meta: {
      year: 2015,
      people: 'mary'
    }
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Delete an object

You can use ‘delete’ to delete an object:

var co = require('co');
var OSS = require('ali-oss')
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  var result = yield client.delete('object-key');
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Delete objects in batches

The following code uses ‘deleteMulti’ to delete objects in batches. You can set the ‘quiet’ parameter to determine whether to return the deletion results:

var co = require('co');
var OSS = require('ali-oss')
var client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: 'Your bucket name'
});
co(function* () {
  var result = yield client.deleteMulti(['obj-1', 'obj-2', 'obj-3']);
  console.log(result);
  var result = yield client.deleteMulti(['obj-1', 'obj-2', 'obj-3'], {
    quiet: true
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});