OSS SDK for Ruby provides API operations to manage multiple objects in a bucket.

List all objects in a bucket

You can call the bucket.list_objects operation to list all objects in a specified bucket. You can specify the following parameters when you list the objects:

  • :prefix: lists objects whose names contain the specified prefix.
  • :marker: lists objects whose names are alphabetically greater than the value of marker.
  • :delimiter: obtains the common prefix of objects.

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

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access Object Storage Service (OSS) because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine Q&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')
# List all objects. 
objects = bucket.list_objects
objects.each { |o| puts o.key }

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

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

List directories

OSS uses a flat structure for objects instead of a hierarchical structure to store objects. A directory is an object whose size is 0 and whose name ends with a forward slash (/). You can upload and download this object. By default, objects whose names end with a forward slash (/) are displayed as directories in the OSS console.

Assume that the following objects are stored in a specific bucket:

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

The following code provides an example on how to use the list_dir function to list objects and subdirectories in a specific directory:

require 'aliyun/oss'

client = Aliyun::OSS::Client.new(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')

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 following result is returned:

> 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 some attributes of the object. These attributes are called object metadata. The metadata of an object is uploaded and downloaded together with the object.

In OSS SDK for Ruby, the metadata of an object is represented by a Hash that contains multiple object attributes. Other keys and values are of the String type. Object metadata is transferred as HTTP headers in requests and responses. According to the HTTP protocol, HTTP headers cannot contain complex characters. Therefore, object metadata can contain only visible ASCII characters. Metadata cannot contain line feeds.
Note The metadata of an object cannot exceed 8 KB in size.

When you use bucket.put_object, bucket.append_object, and bucket.resumable_upload, you can set 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(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')

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 bucket.update_object_metas to update the object metadata:

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')

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

Copy an object

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 by using one of the following methods:

  • If meta is not specified, the metadata of the source object is copied to the destination object.
  • If meta is specified, the specified object metadata is used as the metadata of the destination object.

The following code provides an example on how to copy an object:

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')

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

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

Delete objects

Warning You cannot recover deleted objects. Exercise caution when you perform this operation.
  • Delete a single object

    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(
      # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
      endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
      # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
    
    # Specify the bucket name. Example: examplebucket. 
    bucket = client.get_bucket('examplebucket')
    # Specify the name of the object that you want to delete. 
    bucket.delete_object('my-object')            
  • Deletes 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 information about deleted objects.

    require 'aliyun/oss'
    client = Aliyun::OSS::Client.new(
      # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
      endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
      # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
      access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
    
    # Specify the bucket name. Example: examplebucket. 
    bucket = client.get_bucket('examplebucket')
    # Specify the names of the objects that you want to delete. 
    objs = ['my-object-1', 'my-object-2']
    result = bucket.batch_delete_objects(objs)
    # By default, the information about deleted objects is returned. 
    puts result #['my-object-1', 'my-object-2']
    
    objs = ['my-object-3', 'my-object-4']
    result = bucket.batch_delete_objects(objs, :quiet => true)
    # Specify that the information about deleted objects is not returned. 
    puts result #[]            

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 data from and to the object.
  • public-read: Only the owner or authorized users of this object can write data to the object. Other users, including anonymous users, can only read data from the object.
  • private: Only the owner or authorized users of this object can read and write data from and to the object. Other users, including anonymous users, can access the object only by using a signed URL.
By default, the ACL of an object is set to default when the object is created. You can use bucket.set_object_acl to modify the ACL of the object.
require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  # Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
  # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')

# Specify the bucket name. Example: examplebucket. 
bucket = client.get_bucket('examplebucket')

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 in which the object is stored.
  • If the ACL of an object is not set to default, the object ACL takes precedence over the ACL of the bucket in which the object is stored when the object is accessed.
  • If the ACL of an object is set to public read or public read/write, you can directly access the object in a browser by using the URL of the object. 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 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')