Manage objects

List all objects

You can call the bucket.list_objects operation to list all objects in a specified bucket. The following list describes the parameters:

• :prefix lists objects whose names contain a specified prefix.
• :marker lists objects whose names come after the marker value.
• :delimiter obtains the common prefix of objects.

The following code provides an example on how to list objects that meet specified conditions in a specified bucket:

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 in the bucket.
objects = bucket.list_objects
objects.each { |o| puts o.key }

# List all objects whose names contain the prefix of 'my-' in the bucket.
objects = bucket.list_objects(:prefix => 'my-')
objects.each { |o| puts o.key }

# List all objects whose names contain the prefix of 'my-' and come after the 'my-object' marker in the bucket.
objects = bucket.list_objects(:prefix => 'my-', :marker => 'my-object')
objects.each { |o| puts o.key }
			

List folders

Objects are the basic units for data operations in OSS. OSS does not use a hierarchical structure for objects, but instead uses a flat structure. All elements are stored as objects in buckets. However, OSS supports folders as common prefixes to group objects and simplify management. For more information about common prefixes, see View the object list.

Example: A bucket 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
			

You can call the list_dir function to list objects and subfolders in a specified folder.

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
			

A similar output is displayed:

> 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
			

Manage object metadata

When you upload an object to OSS, you can specify certain attributes of the object in addition to the object content itself. These attributes are called object metadata. Object metadata is stored together with the object during the upload, and returned together with the object during the download.

When you use bucket.put_object, bucket.append_object, and bucket.resumable_upload, you can specify the :metas parameter to specify object metadata.

The following code provides an example on how to specify the object 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')

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'})
			

The following code provides an example on how to use the bucket.update_object_metas command to update the object 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')

bucket.update_object_metas('my-object', {'year' => '2017'})
			

Copy objects

You can call bucket.copy_object to copy an object and use the :meta_directive parameter to specify the object metadata. When you copy an object, you can process the object metadata in one of the following ways:

• If meta is not specified, the metadata of the source object is copied.
• If meta is specified, the specified object metadata overwrites the metadata of the source object.

The following code provides an example on how to copy 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')

# Copy the metadata of the source object.
bucket.copy_object(
  'my-object', 'copy-object',
  :meta_directive => Aliyun::OSS::MetaDirective::COPY)

# Overwrite the metadata of the source object.
bucket.copy_object(
  'my-object', 'copy-object',
  :metas => {'year' => '2017'},
  :meta_directive => Aliyun::OSS::MetaDirective::REPLACE)
			

Delete objects

The following code provides an example on how to call 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 multiple objects

The following code provides an example on how to call bucket.batch_delete_objects to delete multiple objects. You can use the :quiet parameter to specify whether to return the deleted 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')

objs = ['my-object-1', 'my-object-2']
result = bucket.batch_delete_objects(objs)
puts result #['my-object-1', 'my-object-2']. By default, the deleted objects are returned.

objs = ['my-object-3', 'my-object-4']
result = bucket.batch_delete_objects(objs, :quiet => true)
puts result #[]. The deleted objects are not returned.
			

Configure the ACL of an object

You can set the ACL of an object to one of the following values:

• default: The object inherits the ACL of the bucket to which the object belongs. The ACL of the object is the same as that of the bucket in which the object is stored.
• public-read-write: All users, including anonymous users, can read and write the object.
• public-read: Only the owner or authorized users of this bucket can write data to the object in the bucket. Other users, including anonymous users, can only read the object in the bucket.
• private: Only the owner or authorized users of this bucket can read and write data to the object in the bucket. Other users, including anonymous users, can access the object by using a signed URL.

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

bucket = client.get_bucket('my-bucket')

acl = bucket.get_object_acl('my-object')
puts acl # default
bucket.set_object_acl('my-object', Aliyun::OSS::ACL::PUBLIC_READ)
acl = bucket.get_object_acl('my-object')
puts acl # public-read
				

• If you do not set the object ACL, the object inherits the ACL of the bucket to which the object belongs. The ACL of the object is the same as that of the bucket in which the object is stored.
• If an object is configured with an ACL other than the default ACL, the object ACL takes precedence when the object is accessed.
• If an object has an ACL set to public read or public read/write and can thus be accessed by anonymous users, you can access the object by using a URL through a browser. Example: http://bucket-name.oss-cn-hangzhou.aliyuncs.com/object.jpg.
• You can create an anonymous client to access an object whose ACL is public read or public read/write.

      require 'aliyun/oss'
  
      # If you do not specify the access_key_id and access_key_secret, an anonymous client is created. The client can only access objects whose ACL is public read or public read/write.
      client = Aliyun::OSS::Client.new(endpoint: 'endpoint')    
  
      bucket.get_object('my-object', :file => 'local_file')