OSS Ruby SDKは、オブジェクトアップロードのための豊富なインターフェースを提供します。OSSからオブジェクトをアップロードするには、次のいずれかの方法を使用します。
- Upload a local file to the OSS
- Stream upload
- Resumable upload
- Append upload
- Upload callback
ローカルファイルをアップロードする
次のコードでは、ローカルファイルをOSSにアップロードするために指定された:file
パラメータで Bucket#put_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.put_object('my-object', :file => 'local-file')
ストリームアップロード
大きなファイルをアップロードする際に、すべてのコンテンツを一度に処理してアップロードするのではなく、ストリーミング形式でファイルをアップロードする必要があることがよくあります。私たちは一度にコンテンツの一部をアップロードしたいと思います。特に、アップロードするコンテンツがインターネットからresumable_upload 、一度に取得できない場合は、ストリームのアップロードが唯一の選択となります。次のコードでは、ストリームから生成されたコンテンツをOSSにアップロードするために指定されたblock
パラメータでBucket#put_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.put_object('my-object') do |stream|
100.times { |i| stream << i.to_s }
end
再開可能なアップロード
大きなオブジェクトがアップロードされているときにネットワークジッタまたはプログラムがクラッシュすると、アップロード操作全体が失敗します。リソースを無駄にして、オブジェクトを再アップロードする必要があります。ネットワークが不安定な場合は、複数回再試行する必要があります。 The Bucket#resumable_upload
インタフェースは、再開可能なアップロードを実現するために使用できます。インタフェースには次のパラメータがあります。
- key: アップロードされたファイルにマップされたOSS上のオブジェクトの名前。
- file: アップロードするファイルのローカルパス。
- opts: オプションのパラメータ。主に以下を含みます。
- :cpt_file: チェックポイントファイルのパス。 指定されていない場合、チェックポイントオブジェクトのパスは、デフォルトでローカルファイルの同じディレクトリの下の
file.cpt
になります。 ‘file’ はローカルファイルの名前です。 - :disable_cpt: このパラメータをtrueに設定すると、アップロード中にアップロードの進行状況が記録されず、アップロードが失敗した場合に再開可能なアップロードが実行されません。
- :part_size: 各partのサイズ。デフォルトのサイズは4 MBです。
- &block: Bucket#resumable_upload インターフェースが呼び出されたときにブロック関数がインポートされた場合、アップロードの進行状況はブロック関数によって処理されます。
- :cpt_file: チェックポイントファイルのパス。 指定されていない場合、チェックポイントオブジェクトのパスは、デフォルトでローカルファイルの同じディレクトリの下の
パラメータの詳細については、 API Documentationを参照してください。
再開可能なアップロードの原則は、アップロードするオブジェクトを複数の部分に分割して別々にアップロードすることです。すべてのpartsがアップロードされると、オブジェクト全体のアップロードが完了します。現在のアップロードの進捗状況は、アップロードプロセス中に記録されます(checkpoint
オブジェクト内にあります)。プロセス中にアップロードが失敗した場合、次のアップロードの試みは checkpoint
オブジェクトの記録された位置から開始されます。これには、前回のアップロードで同じ checkpoint
オブジェクトを次の呼び出しで使用する必要があります。アップロードが完了すると、 checkpoint
オブジェクトが削除されます。
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.resumable_upload('my-object', 'local-file') do |p|
puts "Progress: #{p}"
end
bucket.resumable_upload(
'my-object', 'local-file',
:part_size => 100 * 1024, :cpt_file => '/tmp/x.cpt') { |p|
puts "Progress: #{p}"
}
注意:
- SDKはアップロード中間状態をcptオブジェクトに記録します。したがって、cptオブジェクトに対する書き込み権限があることを確認してください。
- cptオブジェクトは、アップロードの中間状態情報を記録し、自己チェック機能を持ちます。オブジェクトを編集することはできません。 cptオブジェクトが壊れているとアップロードが失敗します。アップロードが完了すると、
checkpoint
オブジェクトが削除されます。- アップロード処理中にローカルファイルが変更された場合、アップロードは失敗します。
アップロードを追加する
OSSは、追加可能なオブジェクトタイプをサポートしています。Bucket#append_object
インターフェースは、追加可能オブジェクトをアップロードするために使用されます。 このメソッドを呼び出すときは、オブジェクトの追加位置を指定する必要があります。オブジェクトが新しく作成された場合、追加位置は0です。 オブジェクトがすでに存在する場合は、追加位置は、追加する前のオブジェクトの長さに設定する必要があります。
- 追加するオブジェクトが存在しない場合、
append_object
を呼び出すと、追加可能なオブジェクトが作成されます。 - 追加するオブジェクトが存在する場合、
append_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')
# Create an appendable object
bucket.append_object('my-object', 0) {}
# Append content to the end of the object
next_pos = bucket.append_object('my-object', 0) do |stream|
100.times { |i| stream << i.to_s }
end
next_pos = bucket.append_object('my-object', next_pos, :file => 'local-file-1')
next_pos = bucket.append_object('my-object', next_pos, :file => 'local-file-2')
注意:
- 追加可能なオブジェクト (
append_object
を使用して作成されたオブジェクト)にのみコンテンツを追加できます。- 追加可能なオブジェクトはコピーできません。
アップロードコールバック
ファイルをアップロードするときに “アップロードコールバック” を指定することができます。 ファイルがOSSに正常にアップロードされると、OSSは提供したサーバーアドレスへのHTTP POST要求を開始します。この要求は、通知メカニズムと同じです。受信したコールバックの結果に従って操作を実行できます。アップロードコールバックの詳細については、 アップロードコールバックを参照してください。
現在、OSSの put_object
と resumable_upload
インターフェースだけがアップロードコールバックをサポートしています。
require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
endpoint: 'endpoint',
access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
callback = Aliyun::OSS::Callback.new(
url: 'http://10.101.168.94:1234/callback',
query: {user: 'put_object'},
body: 'bucket=${bucket}&object=${object}'
)
begin
bucket.put_object('files/hello', file: '/tmp/x', callback: callback)
rescue Aliyun::OSS::CallbackError => e
puts "Callback failed: #{e.message}"
end
上記のコードでは、アップロードコールバックを指定してファイルを put_object
インターフェイス経由でアップロードします。コールバック本体には、このアップロードのバケットおよびオブジェクト情報が含まれています。コールバックを受信すると、アプリケーションサーバは、ファイルがOSSに正常にアップロードされたと判断します。
resumable_upload
インターフェースの使い方も同様です。
require 'aliyun/oss'
client = Aliyun::OSS::Client.new(
endpoint: 'endpoint',
access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
bucket = client.get_bucket('my-bucket')
callback = Aliyun::OSS::Callback.new(
url: 'http://10.101.168.94:1234/callback',
query: {user: 'put_object'},
body: 'bucket=${bucket}&object=${object}'
)
begin
bucket.resumable_upload('files/hello', '/tmp/x', callback: callback)
rescue Aliyun::OSS::CallbackError => e
puts "Callback failed: #{e.message}"
end
注意:
- コールバックURL must not に
:query
パラメータで指定する必要のあるクエリ文字列を含めることはできません。-ファイルが正常にアップロードされたが、コールバックの実行が失敗した場合、クライアントはCallbackError
をスローします。エラーを無視するには、明示的にエラーをキャッチする必要があります。- 詳細な例については、 callback.rbを参照してください。
- コールバックをサポートするサーバについては、 callback_server.rbを参照してください。