ドキュメントセンター
edit-icon download-icon

オブジェクトをアップロードする

最終更新日: Aug 25, 2017

OSS Ruby SDKは、オブジェクトアップロードのための豊富なインターフェースを提供します。OSSからオブジェクトをアップロードするには、次のいずれかの方法を使用します。

  • Upload a local file to the OSS
  • Stream upload
  • Resumable upload
  • Append upload
  • Upload callback

ローカルファイルをアップロードする

次のコードでは、ローカルファイルをOSSにアップロードするために指定された:fileパラメータで Bucket#put_object インタフェースを使用します。

  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  8. bucket.put_object('my-object', :file => 'local-file')

ストリームアップロード

大きなファイルをアップロードする際に、すべてのコンテンツを一度に処理してアップロードするのではなく、ストリーミング形式でファイルをアップロードする必要があることがよくあります。私たちは一度にコンテンツの一部をアップロードしたいと思います。特に、アップロードするコンテンツがインターネットからresumable_upload 、一度に取得できない場合は、ストリームのアップロードが唯一の選択となります。次のコードでは、ストリームから生成されたコンテンツをOSSにアップロードするために指定されたblock パラメータでBucket#put_objectインタフェースを使用しています。

  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  8. bucket.put_object('my-object') do |stream|
  9.   100.times { |i| stream << i.to_s }
  10. 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 インターフェースが呼び出されたときにブロック関数がインポートされた場合、アップロードの進行状況はブロック関数によって処理されます。

パラメータの詳細については、 API Documentationを参照してください。

再開可能なアップロードの原則は、アップロードするオブジェクトを複数の部分に分割して別々にアップロードすることです。すべてのpartsがアップロードされると、オブジェクト全体のアップロードが完了します。現在のアップロードの進捗状況は、アップロードプロセス中に記録されます(checkpoint オブジェクト内にあります)。プロセス中にアップロードが失敗した場合、次のアップロードの試みは checkpoint オブジェクトの記録された位置から開始されます。これには、前回のアップロードで同じ checkpoint オブジェクトを次の呼び出しで使用する必要があります。アップロードが完了すると、 checkpoint オブジェクトが削除されます。

  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  8. bucket.resumable_upload('my-object', 'local-file') do |p|
  9.   puts "Progress: #{p}"
  10. end
  12. bucket.resumable_upload(
  13.   'my-object', 'local-file',
  14.   :part_size => 100 * 1024, :cpt_file => '/tmp/x.cpt') { |p|
  15.   puts "Progress: #{p}"
  16. }

注意:

  • SDKはアップロード中間状態をcptオブジェクトに記録します。したがって、cptオブジェクトに対する書き込み権限があることを確認してください。
  • cptオブジェクトは、アップロードの中間状態情報を記録し、自己チェック機能を持ちます。オブジェクトを編集することはできません。 cptオブジェクトが壊れているとアップロードが失敗します。アップロードが完了すると、 checkpoint オブジェクトが削除されます。
  • アップロード処理中にローカルファイルが変更された場合、アップロードは失敗します。

アップロードを追加する

OSSは、追加可能なオブジェクトタイプをサポートしています。Bucket#append_object インターフェースは、追加可能オブジェクトをアップロードするために使用されます。 このメソッドを呼び出すときは、オブジェクトの追加位置を指定する必要があります。オブジェクトが新しく作成された場合、追加位置は0です。 オブジェクトがすでに存在する場合は、追加位置は、追加する前のオブジェクトの長さに設定する必要があります。

  • 追加するオブジェクトが存在しない場合、append_object を呼び出すと、追加可能なオブジェクトが作成されます。
  • 追加するオブジェクトが存在する場合、append_objectを呼び出すと、そのオブジェクトの最後にコンテンツが追加されます。
  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  8. # Create an appendable object
  9. bucket.append_object('my-object', 0) {}
  11. # Append content to the end of the object
  12. next_pos = bucket.append_object('my-object', 0) do |stream|
  13.   100.times { |i| stream << i.to_s }
  14. end
  15. next_pos = bucket.append_object('my-object', next_pos, :file => 'local-file-1')
  16. next_pos = bucket.append_object('my-object', next_pos, :file => 'local-file-2')

注意:

  • 追加可能なオブジェクト (append_objectを使用して作成されたオブジェクト）にのみコンテンツを追加できます。
  • 追加可能なオブジェクトはコピーできません。

アップロードコールバック

ファイルをアップロードするときに “アップロードコールバック” を指定することができます。 ファイルがOSSに正常にアップロードされると、OSSは提供したサーバーアドレスへのHTTP POST要求を開始します。この要求は、通知メカニズムと同じです。受信したコールバックの結果に従って操作を実行できます。アップロードコールバックの詳細については、 アップロードコールバックを参照してください。

現在、OSSの put_object と resumable_uploadインターフェースだけがアップロードコールバックをサポートしています。

  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  9. callback = Aliyun::OSS::Callback.new(
  10.   url: 'http://10.101.168.94:1234/callback',
  11.   query: {user: 'put_object'},
  12.   body: 'bucket=${bucket}&object=${object}'
  13. )
  15. begin
  16.   bucket.put_object('files/hello', file: '/tmp/x', callback: callback)
  17. rescue Aliyun::OSS::CallbackError => e
  18.   puts "Callback failed: #{e.message}"
  19. end

上記のコードでは、アップロードコールバックを指定してファイルを put_objectインターフェイス経由でアップロードします。コールバック本体には、このアップロードのバケットおよびオブジェクト情報が含まれています。コールバックを受信すると、アプリケーションサーバは、ファイルがOSSに正常にアップロードされたと判断します。

resumable_upload インターフェースの使い方も同様です。

  1. require 'aliyun/oss'
  3. client = Aliyun::OSS::Client.new(
  4.   endpoint: 'endpoint',
  5.   access_key_id: 'AccessKeyId', access_key_secret: 'AccessKeySecret')
  7. bucket = client.get_bucket('my-bucket')
  9. callback = Aliyun::OSS::Callback.new(
  10.   url: 'http://10.101.168.94:1234/callback',
  11.   query: {user: 'put_object'},
  12.   body: 'bucket=${bucket}&object=${object}'
  13. )
  15. begin
  16.   bucket.resumable_upload('files/hello', '/tmp/x', callback: callback)
  17. rescue Aliyun::OSS::CallbackError => e
  18.   puts "Callback failed: #{e.message}"
  19. end

注意:

  • コールバックURL must not に :query パラメータで指定する必要のあるクエリ文字列を含めることはできません。-ファイルが正常にアップロードされたが、コールバックの実行が失敗した場合、クライアントは CallbackErrorをスローします。エラーを無視するには、明示的にエラーをキャッチする必要があります。
  • 詳細な例については、 callback.rbを参照してください。
  • コールバックをサポートするサーバについては、 callback_server.rbを参照してください。