Document Center
edit-icon download-icon

Upload objects

Last Updated: Dec 22, 2017

The OSS Ruby SDK provides rich interfaces for object upload. You can upload an object from OSS through any of the following methods:

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

Upload a local file

The following code uses the Bucket#put_object interface with the :file parameter specified to upload a local file to OSS:

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

Stream upload

During uploading a large file, we often need to upload the file in a streaming way instead of processing and uploading all the content at the same time. We want to upload a part of content at a time. In particular, when the content to be uploaded comes from the Internet and cannot be retrieved at the same time, stream upload is the only option left. The following code uses the Bucket#put_object interface with the block parameter specified to upload the content generated from a stream to the OSS:

  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

Resumable upload

If the network jitters or the program crashes when a large object is being uploaded, the whole upload operation fails. You have to re-upload the objects, wasting resources. When the network is unstable, you may need to make multiple retries. The Bucket#resumable_upload interface can be used to achieve resumable upload. The interface has the following parameters:

  • key: The name of the object on OSS mapped to the uploaded file.
  • file: The local path of the file to be uploaded.
  • opts: An optional parameter. It mainly includes:
    • :cpt_file: The path of the checkpoint file. If not specified, the path of the checkpoint object is by default the file.cpt under the same directory of the local file. The ‘file’ is the name of the local file.
    • :disable_cpt: If this parameter is set to true, the upload progress is not recorded during upload, and resumable upload is not performed when upload fails.
    • :part_size: The size of each part. The default size is 4 MB.
    • &block: If a block function is imported when the Bucket#resumable_upload interface is called, the upload progress is handled by the block function.

For more information about the parameters, see API Documentation.

The principle of resumable upload is to divide the object to be uploaded into multiple parts and upload them separately. When all the parts are uploaded, the upload of the entire object is completed. The progress of the current upload is recorded during the uploading process(in the checkpoint object). If the upload of any part fails during the process, the next upload attempt starts from the recorded position in the checkpoint object. This requires that the same checkpoint object with the previous upload must be used in the next call. When the upload is completed, the checkpoint object is deleted.

  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. }

Note:

  • The SDK records the upload intermediate states in the cpt object. Therefore, make sure that you have the write permission on the cpt object.
  • The cpt object records the intermediate state information of the upload and has a self-checking function. You cannot edit the object. Upload fails if the cpt object is corrupted. When the upload is completed, the checkpoint object is deleted.
  • Upload fails if the local file is changed during the upload process.

Append upload

OSS supports the appendable object type. The Bucket#append_object interface is used to upload appendable objects. When calling this method, you must specify the append position of the object. If the object is newly created, the append position is 0. If the object already exists,the append position must be set to the object length before the append.

  • If the object to be appended does not exist, calling append_object creates an appendable object.
  • If the object to be appended exists, calling append_object appends the content to the end of the 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')

Note:

  • You can only append content to appendable objects (objects created using append_object).
  • An appendable object cannot be copied.

Upload callback

You can specify an “upload callback” when uploading a file. After the file is successfully uploaded to OSS, OSS initiates an HTTP POST request to the server address that you have provided. The request is equal to a notification mechanism. You can perform operations according to the received callback results. For more information about upload callback, see OSS Upload Callback.

Currently, only the put_object and resumable_upload interfaces of the OSS support upload callback.

  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

In the preceding code, a file is uploaded through the put_object interface with an upload callback specified. The callback body contains the bucket and object information for this upload. Upon receiving the callback, the application server determines that the file has been successfully uploaded to the OSS.

The usage of the resumable_upload interface is similar: 

  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

Note:

  • The callback URL must not contain the query string which must be specified in the :query parameter.
  • In the event that the file is successfully uploaded but callback execution fails, the client throws CallbackError. To ignore the error, you must explicitly catch the exception.
  • For detailed examples, see callback.rb.
  • For servers that support callback, see callback_server.rb.
Thank you! We've received your feedback.
Free Trial Free Trial