Manage objects

A bucket can have a lot of objects. The SDK provides a series of APIs 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: Only list objects with specific prefixes.
• marker: Only list objects with names after the specified marker.
• delimiter: Obtain the common prefix of a group of objects.
• max-keys: Specify the maximum number of objects to be 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* () {
  // If no parameter is specified, 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 that are prefixed with "my-".
  var result = yield client.list({
    prefix: 'my-'
  });
  console.log(result);
  // List all objects whose names are prefixed with "my-" and after the marker of "my-object".
  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 bythe key of the object, and they are not hierarchical. Such a structure allows users to efficiently store objects in OSS,but some users may want to manage objects in a conventional way by putting different types of objectsunder different “directories”. OSS provides a “Common Prefix” feature to convenientlycreate a stimulated directory structure. For more information about the common prefix, see 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 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 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 meta information

When uploading an object to OSS, you can specify certain property information about the object in addition to the content. The property information is called “meta information”,which is stored together with the object during uploading.

Because the object meta information is stored in HTTP headers during object uploading, the meta information cannot containany complex characters according to HTTP. Therefore, the meta information must only contain simple printable ASCII characters and cannot contain line breaks. Allmeta information cannot exceed 8 KB.

You can specify the object meta information by specifying the meta parameter when using the putand 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.multipartUpload('object-key', 'local-file', {
    meta: {
      year: 2017,
      people: 'mary'
    }
  });
  console.log(result);
}).catch(function (err) {
  console.log(err);
});

Delete objects

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 batch

The following code uses deleteMulti to delete objects in batch. You can set the quiet parameter todetermine 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);
});