管理檔案（Object）

一個Bucket下可能有非常多的檔案，SDK提供一系列的介面方便使用者管理檔案。

查看所有檔案

通過Bucket#list_objects來列出當前Bucket下的所有檔案。主要的參數如下：

:prefix 指定只列出符合特定首碼的檔案
:marker 指定只列出檔案名大於marker之後的檔案
:delimiter 用於獲取檔案的公共首碼

require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
  endpoint: 'endpoint',
  access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
# 列出所有檔案
objects = bucket.list_objects
objects.each { |o| puts o.key }
# 列出首碼為'my-'的所有檔案
objects = bucket.list_objects(:prefix => 'my-')
objects.each { |o| puts o.key }
# 列出首碼為'my-'且在'my-object'之後的所有檔案
objects = bucket.list_objects(:prefix => 'my-', :marker => 'my-object')
objects.each { |o| puts o.key }

模擬目錄結構

OSS是基於對象的儲存服務，沒有目錄的概念。儲存在一個Bucket中所有檔案都是通過檔案的key唯一標識，並沒有層級的結構。這種結構可以讓OSS的儲存非常高效，但是使用者管理檔案時希望能夠像傳統的檔案系統一樣把檔案分門別類放到不同的“目錄”下面。通過OSS提供的“公共首碼”的功能，也可以很方便地模擬目錄結構。公共首碼的概念請參考查看對象列表。

假設Bucket中已有如下檔案：

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

接下來我們實現一個函數叫list_dir，列出指定目錄下的檔案和子目錄：

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

運行結果如下：

> 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

檔案元資訊

向OSS上傳檔案時，除了檔案內容，還可以指定檔案的一些屬性資訊，稱為“元資訊”。這些資訊在上傳時與檔案一起儲存，在下載時與檔案一起返回。

在SDK中檔案元資訊用一個Hash表示，其他key和value都是String類型，並且都只能是簡單的ASCII可見字元。所有元資訊的總大小不能超過8KB。

使用Bucket#put_object、Bucket#append_object和Bucket#resumable_upload時都可以通過指定:metas參數來指定檔案的元資訊：

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

通過Bucket#update_object_metas命令來更新檔案元資訊：

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

拷貝檔案

使用Bucket#copy_object拷貝一個檔案。拷貝時對檔案元資訊的處理有兩種選擇，通過:meta_directive參數指定：

與源檔案相同，即拷貝源檔案的元資訊
使用新的元資訊覆蓋源檔案的資訊

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.copy_object(
  'my-object', 'copy-object',
  :meta_directive => Aliyun::OSS::MetaDirective::COPY)
# 覆蓋檔案元資訊
bucket.copy_object(
  'my-object', 'copy-object',
  :metas => {'year' => '2017'},
  :meta_directive => Aliyun::OSS::MetaDirective::REPLACE)

刪除檔案

通過Bucket#delete_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')

大量刪除檔案

通過Bucket#batch_delete_object大量刪除檔案，使用者可以通過:quiet參數來指定是否返回刪除的結果：

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']，預設返回刪除成功的檔案
objs = ['my-object-3', 'my-object-4']
result = bucket.batch_delete_object(objs, :quiet => true)
puts result #[]，不返回刪除的結果