Manage objects - SDK Reference| Alibaba Cloud Documentation Center

A bucket may have a lot of objects. SDK provides a series of interfaces to help in managing the objects easily.

View all objects

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

Prefix: Specifies only list objects with specific prefixes.
Marker: Specifies list objects whose names are greater than a specified marker.
Delimiter: Obtains the common prefix of a group of objects.
Max-keys: Specifies 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. These objects does not follow any hierarchical structure amongst themselves. Such structure allows OSS to store objects efficiently.

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 that helps to create a stimulated directory structure. For more information about the public prefix concept, see View the object list.

Assuming 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 enlist 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 have to specify certain attribute information for the object. This attribute information is called meta information.

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

This is 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 must 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 must be in the format of‘/bucket/object’.

Additionally, when an object is copied, two methods can be used to process the object metadata:

If no ‘meta’ parameter is specified, the metadata remains same as 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 the 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 multiple objects

The following code uses ‘deleteMulti’ to delete multiple objects. 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);
});