Aliyun OSS SDK

Build Status Code Climate Coverage Status

It is a full-featured Ruby Library for Aliyun OSS API. We provide two ways to help you use the API: Function based and Object based. Besides, We try to keep things natural and reasonable, but there are always some leaky, welcome to give us advice and modification. Enjoy it!

Installation

It's a Ruby Gem, so you can install it like any Gem:

gem install aliyun-oss-sdk

If you use Gemfile manage your Gems, Add below to your Gemfile.

gem "aliyun-oss-sdk"

And run:

bundle install

Document

Here is original Restful API, It has the most detailed and authoritative explanation for every API.

Here is thr RDoc Document for this Library, use to find mostly usage for methods.

Here are some more guides for help you. Welcome to advice.

Function Based

Object Based

Usage

Quick Start

Function Based

require 'aliyun/oss'

# ACCESS_KEY/SECRET_KEY is your access credentials
# host: your bucket's data center host, eg: oss-cn-hangzhou.aliyuncs.com
# Details: https://docs.aliyun.com/#/pub/oss/product-documentation/domain-region#menu2
# bucket: your bucket name

client = Aliyun::OSS::Client.new('ACCESS_KEY', 'SECRET_KEY', host: 'oss-cn-hangzhou.aliyuncs.com', bucket: 'oss-sdk-dev-hangzhou')


# Upload object
client.bucket_create_object('image.png', File.new('path/to/image.png'), { 'Content-Type' => 'image/png' })

# Get Object
client.bucket_get_object('image.png')


# Get all objects in this bucket
# use prefix，marker，delimiter, max-keys to filter results
client.bucket_list_objects()

Object Based

require 'aliyun/oss'

# ACCESS_KEY/SECRET_KEY is your access credentials
# host: your bucket's data center host, eg: oss-cn-hangzhou.aliyuncs.com
# Details: https://docs.aliyun.com/#/pub/oss/product-documentation/domain-region#menu2
# bucket: your bucket name

client = Aliyun::OSS::Client.new('ACCESS_KEY', 'SECRET_KEY', host: 'oss-cn-hangzhou.aliyuncs.com', bucket: 'oss-sdk-dev-hangzhou')


# Upload object
client.bucket_objects.create('image.png', File.new('path/to/image.png'), { 'Content-Type' => 'image/png' })

# Get Object
client.bucket_objects.get('image.png')

# Get all objects in this bucket
# use prefix，marker，delimiter, max-keys to filter results
client.bucket_objects.list()

#### Objects #####        
buckets = client.buckets
bucket_objects = client.bucket_objects
bucket_multiparts = client.bucket_multiparts
bucket = client.buckets.list.first  || Aliyun::Oss::Struct::Bucket.new(name: bucket_name, client: client)
multipart = client.bucket_multiparts.list.first || Aliyun::Oss::Struct::Multipart.new(upload_id: upload_id, key: object_key, client: client)
bucket_object = client.bucket_objects.list.first || Aliyun::Oss::Struct::Object.new(key: object_key, client: client)

Share your files

Sometimes, you want to share some file in your private bucket with your friends , but you donot want to share your AccessKey, thus, Aliyun provide alternative way: Put signature in URL

We provide a method to calculate signature for you:

# Return Singature string
Aliyun::Oss::Authorization.get_temporary_signature('SECRET_KEY', Time.now.to_i + 60*60, verb: 'GET', bucket: 'bucket-name', key: 'object-name')

Directly POST file to Aliyun OSS

Sometime we may allow user directly upload image or file to Aliyun to improve the upload speed. thus you may need POST form: Post Object

With Post Form, we need Post Policy to restrict permissions, here we provide two methods that you may interesting:

 # policy your policy in hash
 # Return base64 string which can used to fill your form field: policy
 client.get_base64_policy(policy)

 # Get Signature for policy
 # Return Signature with policy, can used to fill your form field: Signature
 client.get_policy_signature(SECRET_KEY, policy)

API Mapping

We provide two type API: Function Based, Object Based. To help you find your needed methods, here list a mapping from Original Restful API to our methods.

Note:

  • All Function Based API are instance methods of Aliyun::Oss::Client

  • Object Based API belongs to some other class list below:

    • buckets: Aliyun::Oss::Client::BucketsService
    • bucket_objects: Aliyun::Oss::Client::BucketObjectsService
    • bucket_multiparts: Aliyun::Oss::Client::BucketMultipartsService
    • bucket: Aliyun::Oss::Struct::Bucket
    • multipart: Aliyun::Oss::Struct::Multipart
    • object: Aliyun::Oss::Struct::Object

| Restful API | Function Based | Object Based | |---|---| |GetService (ListBucket) |bucket_list |buckets#list | |Put Bucket |bucket_create | buckets#create| |Put Bucket Acl |bucket_set_acl | bucket#set_acl| |Put Bucket Logging|bucket_enable_logging | bucket#enable_logging| |Put Bucket Website |bucket_enable_website | bucket#enable_website| |Put Bucket Referer |bucket_set_referer | bucket#set_referer| |Put Bucket Lifecycle | bucket_enable_lifecycle| bucket#enable_lifecycle| |Get Bucket (List Object) | bucket_list_objects| bucket_objects#list| |Get Bucket ACL | bucket_get_acl| bucket#acl!| |Get Bucket Location| bucket_get_location| bucket#location!| |Get Bucket Logging | bucket_get_logging| bucket#logging!| |Get Bucket Website | bucket_get_website| bucket#website!| |Get Bucket Referer | bucket_get_referer| bucket#referer!| |Get Bucket Lifecycle | bucket_get_lifecycle| bucket#lifecycle!| |Delete Bucket | bucket_delete| buckets#delete| |Delete Bucket Logging | bucket_disable_logging| bucket#disable_logging| |Delete Bucket Website | bucket_disable_website| bucket#disable_website| |Delete Bucket Lifecycle | bucket_disable_lifecycle| bucket#disable_lifecycle| |Put Object| bucket_create_object| bucket_objects#create| |Copy Object | bucket_copy_object| bucket_objects#copy| |Get Object | bucket_get_object| bucket_objects#get| |Append Object| bucket_append_object| bucket_objects#append| |Delete Object| bucket_delete_object| bucket_objects#delete| |Delete Multiple Objects| bucket_delete_objects| bucket_objects#delete_multiple| |Head Object | bucket_preflight| bucket#preflight, bucket#options| |Put Object ACL | bucket_set_object_acl| object#set_acl| |Get Object ACL | bucket_get_object_acl| object#acl!| |Post Object | ...| ...| |Initiate Multipart Upload | bucket_init_multipart| bucket_multiparts#init| |Upload Part | bucket_multipart_upload| multipart#upload| |Upload Part Copy | bucket_multipart_copy_upload| multipart#copy| |Complete Multipart Upload | bucket_complete_multipart| multipart#complete| |Abort Multipart Upload | bucket_abort_multipart| multipart#abort| |List Multipart Uploads | bucket_list_multiparts| bucket_multiparts#list| |List Parts | bucket_list_parts| multipart#list_parts| |Put Bucket cors | bucket_enable_cors| bucket#enable_cors| |Get Bucket cors | bucket_get_cors| bucket#cors!| |Delete Bucket cors | bucket_disable_cors| bucket#disable_cors| |OPTIONS Object| bucket_get_meta_object| object#meta!|

Test

We use minitest for test and rubocop for Syntax checker, If you want to make contribute to this library. Confirm below Command is success:

bundle exec rake test

Authors && Contributors

License

licensed under the Apache License 2.0