OSS SDK for Ruby provides API operations for you to manage multiple objects in a bucket.
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.
Hash
parameter specifies the hash value of the object metadata. Other keys and values
are of the String
type. Object metadata is included in HTTP request headers. The request headers cannot
contain complex characters to comply with HTTP specifications. Therefore, object metadata
can contain only simple printable ASCII characters and cannot contain new line.
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.
bucket.set_object_acl
to set the object ACL.
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')