Manage objects

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 Bucket#list_objects 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 objects

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
# List all objects
objects = bucket.list_objects
objects.each { |o| puts o.key }
# List all objects with the "my-" prefix in the name
objects = bucket.list_objects(:prefix => 'my-')
objects.each { |o| puts o.key }
# List all objects that follow the "my-object" marker and whose names contain the "my-" prefix
objects = bucket.list_objects(:prefix => 'my-', :marker => 'my-object')
objects.each { |o| puts o.key }

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. No hierarchical structure is established 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 concept of a public prefix, see View Object List.

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 named list_dir to list all objects and subdirectories in a specified directory:

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
def list_dir(dir)
  objects = bucket.list_objects(:prefix => dir, :delimiter => '/')
  objects.each do |obj|
    if obj.is_a?(OSS::Object) # object
      puts "Object: #{obj.key}"
    else # common prefix
      puts "SubDir: #{obj}"
    end
  end
end

The execution results are as follows:

> list_dir('foo/')
=> SubDir: foo/bar/
   SubDir: foo/hello/
   Object: foo/x
   Object: foo/y
> list_dir('foo/bar/')
=> Object: foo/bar/a
   Object: foo/bar/b
> list_dir('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.

In the SDK, the metadata of an object is expressed by a Hash, and the object key and value are both of the String type, and only contain simple printable ASCII characters and cannot contain line breaks. The total size of all metadata cannot exceed 8 KB.

Note: Because the object meta information is stored in HTTP headers during object uploading/downloading, the meta information cannot contain any complex character according to HTTP.

When using Bucket#put_object, Bucket#append_object, and Bucket#resumable_upload, you can specify the object metadata by specifying the :metas parameter.

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
bucket.put_object(
  'my-object-1',
  :file => 'local-file',
  :metas => {'year' => '2016', 'people' => 'mary'})
bucket.append_object(
  'my-object-2', 0,
  :file => 'local-file',
  :metas => {'year' => '2016', 'people' => 'mary'})
bucket.resumable_upload(
  'my-object',
  'local-file',
  :metas => {'year' => '2016', 'people' => 'mary'})

Run the Bucket#update_object_metas command to update the metadata of an object.

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
bucket.update_object_metas('my-object', {'year' => '2017'})

Copy an object

The following code uses Bucket#copy_object to copy an object. When an object is copied, two methods can be used to process the object metadata. The method used is specified by the :meta_directive parameter:

• Method 1: Stay consistent with the source object metadata through the COPY operation.
• Method 2: Overwrite the source object metadata with the new metadata.

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
# Copy the source object metadata
bucket.copy_object(
  'my-object', 'copy-object',
  :meta_directive => Aliyun::OSS::MetaDirective::COPY)
# Overwrite the source object metadata
bucket.copy_object(
  'my-object', 'copy-object',
  :metas => {'year' => '2017'},
  :meta_directive => Aliyun::OSS::MetaDirective::REPLACE)

Delete an object

The following code uses Bucket#delete_object to delete an object:

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
bucket.delete_object('my-object')

Delete objects in batches

The following code uses Bucket#batch_delete_object to delete objects in batches. You can set the :quiet parameter to determine whether to return the deletion results:

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
objs = ['my-object-1', 'my-object-2']
result = bucket.batch_delete_object(objs)
puts result #['my-object-1', 'my-object-2']. Names of successfully deleted objects are returned by default. 
objs = ['my-object-3', 'my-object-4']
result = bucket.batch_delete_object(objs, :quiet => true)
puts result #[]. The deletion result is not returned.