Objects are the basic unit for data operations in Object Storage Service (OSS). OSS SDK for Ruby provides a variety of methods to upload objects.

Upload a local file

The following code provides an example on how to call Bucket#put_object and set the :file parameter to upload a local file to OSS:

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

Streaming upload

If a long period of time is required to upload a large object, you can use streaming upload to upload the object in increments until the entire object is uploaded.

The following code provides an example on how to call Bucket#put_object and set the block parameter to upload an object to OSS by using streaming 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')
bucket.put_object('my-object') do stream
  100.times { i stream << i.to_s }
end
            

Resumable upload

An object can be split into several parts that can be uploaded simultaneously. After all parts are uploaded, they are combined into a complete object.

You can call Bucket#resumable_upload to implement resumable upload. You must configure the following parameters in the operation:

  • key: the name of the object to upload to OSS.
  • file: the path of the local file to upload.
  • opts: an optional parameter that contains the following options.
    • :cpt_file: the path of the checkpoint file. The default value is file.cpt that is in the same directory as the local file. file indicates the name of the local file.
    • :disable_cpt: If you set this option to true, the upload progress is not recorded during the object upload. As a result, if the object fails to upload, the upload cannot be resumed.
    • :part_size: the size of each part. Default value: 4 MB.
    • &block: If you pass in block when you call Bucket#resumable_upload, the upload progress is processed by block.
For more information about the related parameters, see Alibaba Cloud OSS SDK for Ruby.
Note If a part fails to upload, the next upload operation of this object continues from the point recorded in the checkpoint file. Next time you call Bucket#resumable_upload, you must specify the same checkpoint file as last time. The checkpoint file is deleted after the object is uploaded.

The following code provides an example on how to upload an object by using 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')
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}"
}
            
Note
  • OSS SDK for Ruby records upload progress in a cpt file. Make sure that you have write permissions on the cpt file.
  • The cpt file records the intermediate status information of uploads, and can verify uploaded data. You cannot edit the cpt file. If the cpt file is damaged, the upload is interrupted. After the entire object is uploaded, the cpt file is deleted.
  • If changes occur to the local file during upload, the upload fails.

Append upload

You can call Bucket#append_object to upload appendable objects. You must specify the position where the append operation starts. The position must be 0 for the first append operation. The position of the subsequent append operations is the current size of the object.

  • If the object to append does not exist, an appendable object is created when you call append_object.
  • If the object exists, new content is appended to the end of the object when you call 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')
            
Note
  • You can append content only to appendable objects.
  • Appendable objects cannot be copied.

Upload callback

You can configure upload callback when you upload an object. Then, after the object is uploaded, OSS sends an HTTP POST request to the application server address that you provide. This way, the application server is informed of the upload. For more information about upload callback, see Upload callback.
Note You can call only put_object or resumable_upload to upload an object and configure upload callback at the same time. For more information about the complete sample code that is used to configure upload callback, visit GitHub.

When you call put_object to upload an object and configure upload callback at the same time, you must specify the related bucket and the object information in the body field. If the application server receives the callback request, the object is uploaded to OSS.

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
            

You can call resumable_upload in a similar way to 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')

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
            
Note
  • The callback URL cannot contain query strings. You must specify query strings in the query parameter.
  • If the object is uploaded but the upload callback failed, the client throws the CallbackError error. If you ignore the error, you must explicitly handle the exception.
  • For more information about the application server that serves as the callback server, visit GitHub.