oss 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f3b2ed6f0211cebe848128e657d3d2de6c9de0ff
-  data.tar.gz: bd5887255606c389a5831a4b7bf1b3c24b8a07fa
+  metadata.gz: c64351f553df8d0f35e61b0b70a8d2ce71f61b41
+  data.tar.gz: 6d3f3b16ce830d02c4772eca63e344c323ef8b88
 SHA512:
-  metadata.gz: af7a50af242a892367eea47d2781171153543b56dae24dad9718fe7fdf6f1b311e66df5d1c002e74884b2f31b20a57c0f6bf29b72a3079301bc540e683c05316
-  data.tar.gz: 1da0ae248563da50cb0c3a3d8b491187f67cbfdb5b11f0aefe51c04e2ad0f811daa4e08b10fa8cd91d06268b43fb65249b77a91d1935ecfe30368154d32c2584
+  metadata.gz: eb5bf2d3528123b8991764b8e77eda0a27b76193550ebaa1a4eb6bb67d3ccd07fe2af94045962271049aa0a719d5a5b6ed9fc5f7440ffebc304488ec33e81fdb
+  data.tar.gz: 9edb1a15057ea3d761c69743e62295b48c9f4c951a30786e7e0ef6d6987d7bbd7977d1317b92c2eca1b131ebc4dd448bf3ba93d45a22beb270af86a44f618fce

data/README.md

@@ -107,6 +107,647 @@ file.close
 ```
 you can find more api options in API Doc `OSS::Object`
 
+## API
+
+### Service Operations
+Class `Oss::Service`
+
+#### .get_service(options)
+
+List buckets in this account.
+
+parameters:
+
+- `options` {Hash} query parameters, default is `nil`
+  - `prefix` {string} search buckets using `prefix` key
+  - `marker` {string} search start from `marker`, including `marker` key
+  - `max_keys` {String} max buckets, default is `100`, limit to `1000`
+  
+```ruby
+service = @api.get_service(prefix: 'prefix')
+```
+Success will return service class object, use chain method get response params.
+
+- `.buckets`
+return buckets Array
+```ruby
+service.buckets.each do |bucket|
+  puts bucket[:location]
+  puts bucket[:name]
+  puts bucket[:creation_date]
+end
+```
+
+- `.owner`
+return owner info
+```ruby
+puts service.owner[:id]
+puts service.owner[:name]
+```
+
+- `.prefix, .marker, .max_keys, .is_truncated, .next_marker`
+return option infos
+```ruby
+puts service.prefix
+puts service.max_keys
+```
+  
+#### .list_buckets
+
+same as get_service, its a alias
+
+### Bucket Operations
+Class `Oss::Bucket`
+
+#### .put_bucket(bucket_name, acl)
+
+Create a new bucket.
+
+parameters:
+
+- `name` {String} bucket name
+- `acl` {String} set bucket acl, `public-read-write`, `public-read`, `private`
+
+```ruby
+@api.put_bucket('bucket_name', 'public-read')
+```
+if success will return true
+
+#### .put_bucket_acl(bucket_name, acl)
+
+Update the bucket ACL.
+
+parameters:
+- `name` {String} bucket name
+- `acl` {String} set bucket acl, `public-read-write`, `public-read`, `private`
+
+```ruby
+@api.put_bucket_acl('bucket_name', 'public-read')
+```
+if success will return true
+
+#### .put_bucket_logging(bucket_name, target_bucket, enable, target_prefix)
+
+Update the bucket logging settings. Log file will create every one hour and name format: <prefix><bucket>-YYYY-mm-DD-HH-MM-SS-UniqueString.
+
+parameters:
+- `name` {String} bucket name
+- `target_bucket` {String} log storage target bucket
+- `enable` {Bool} enable or disable log
+- `target_prefix` {String} log file prefix
+
+```ruby
+@api.put_bucket_logging('bucket_name', 'bucket_name', true, 'prefix-')
+```
+if success will return true
+
+#### .put_bucket_website(bucket_name, index_doc, error_doc)
+
+Set the bucket as a static website.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `index_doc` {String} index file object key
+- `error_doc` {String} error file object key
+
+```ruby
+@api.put_bucket_website('bucket_name', 'index.html', '404.html')
+```
+
+if success will return true
+
+#### .put_bucket_referer(bucket_name, allow_empty, referer_list)
+
+Set the bucket request Referer white list.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `allow_empty` {Bool} allow empty request referer or not
+- `referer_list` {Array} Referer white list, e.g.: [ 'https://www.taobao.com', 'http://www.aliyun.com' ]
+
+```ruby
+referer_list = [ 'https://www.taobao.com', 'http://www.aliyun.com' ]
+@api.put_bucket_referer('bucket_name', true, referer_list)
+```
+
+if success will return true
+
+#### .put_bucket_lifecycle(bucket_name, rules)
+
+Set the bucket object lifecycle.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `rules` {Array} rule config list, each Rule will contains blow properties:
+  - `id` {String} rule id, if not set, OSS will auto create it with random string.
+  - `prefix` {String} store prefix
+  - `status` {Bool} rule status, true or false
+  - `[days]` {Number} expire after the days
+  - `[date]` {String} expire date, e.g.: `2022-10-11T00:00:00.000Z` date and days only set one.
+
+```ruby
+rules = [
+        {id: 'rule1', days: 300, prefix: 'pre-', status: true},
+        {id: 'rule2', date: '2022-10-11T00:00:00.000Z', prefix: 'log-', status: true}
+    ]
+@api.put_bucket_lifecycle('bucket_name', rules)
+```
+
+if success will return true
+
+#### .get_bucket(bucket_name, options)
+
+List objects in the bucket.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `options` query parameters, default is `nil`
+  - `[prefix]` {String} search object using prefix key
+  - `[marker]` {String} search start from marker, including marker key
+  - `[delimiter]` {String} delimiter search scope e.g. / only search current dir, not including subdir
+  - `[max_keys]` {String|Number} max objects, default is 100, limit to 1000
+
+```ruby
+list = @api.get_bucket('bucket_name')
+```
+
+Success will return service class object, use chain method get response params.
+
+- `.contents`
+Success will return objects list on objects properties.
+
+```ruby
+list.contents.each do |object|
+  puts object[:key]
+  puts object[:last_modified]
+  puts object[:etag]
+  puts object[:type]
+  ...
+end
+```
+
+  - `name` {String} object name on oss
+  - `lastModified` {String} object last modified GMT date, e.g.: 2015-02-19T08:39:44.000Z
+  - `etag` {String} object etag contains ", e.g.: "5B3C1A2E053D763E1B002CC607C5A0FE"
+  - `type` {String} object type, e.g.: Normal
+  - `size` {String} object size, e.g.: 344606
+  - `storage_class` {String} storage class type, e.g.: Standard
+  - `owner` {Hash} object owner, including `id` and `display_name`
+
+- `.prefixes` {Array} prefix list
+- `.is_truncated` {Boolean} truncate or not
+- `.next_marker` {String} next marker string
+
+#### .get_bucket_acl(bucket_name)
+
+Get the bucket ACL.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return Hash:
+
+- `grant` {String} acl settings string
+- `owner` {Hash} object owner, including `id` and `display_name`
+
+#### .get_bucket_location(bucket_name)
+
+Get the bucket ACL.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return location string.
+
+```ruby
+puts @api.get_bucket_location('bucket_name')
+```
+
+#### .get_bucket_logging(bucket_name)
+
+Get the bucket logging settings.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return Hash:
+
+- `logging_enabled` {Bool} enable logging or not
+- `target_bucket` {String} log store bucket
+- `target_prefix` {String} log file prefix
+
+```ruby
+log = @api.get_bucket_logging('bucket_name')
+puts log[:logging_enabled]
+puts log[:target_bucket]
+puts log[:target_prefix]
+```
+
+#### .get_bucket_referer(bucket_name)
+
+Get the bucket request Referer white list.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return Hash:
+
+- `allow_empty_referer` {Bool} allow empty request referer or not
+- `referers` {Array} Referer white list
+
+#### .get_bucket_website(bucket_name)
+
+Get the bucket website config.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return Hash:
+
+- `index_doc` {String} index page
+- `error_doc` {String} error page, maybe nil
+
+#### .get_bucket_lifecycle(bucket_name)
+
+Get the bucket object lifecycle.
+
+- `bucket_name` {String} bucket name
+
+Success will return lifecycle rules Array:
+
+- `id` {String} rule id, if not set, OSS will auto create it with random string.
+- `prefix` {String} store prefix
+- `status` {Bool} rule status, true or false
+- `[days]` {Number} expire after the days
+- `[date]` {String} expire date, e.g.: `2022-10-11T00:00:00.000Z` date and days only has one.
+
+#### .delete_bucket_logging(bucket_name)
+
+Delete the bucket logging settings.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return true
+
+#### .delete_bucket_website(bucket_name)
+
+Delete the bucket website config.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return true
+
+#### .delete_bucket_lifecycle(bucket_name)
+
+Delete the bucket object lifecycle.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return true
+
+#### .delete_bucket(bucket_name)
+
+Delete an empty bucket.
+
+- `bucket_name` {String} bucket name
+
+Success will return true
+
+### Object Operations
+Class `Oss::Object`
+
+#### .put_object(bucket_name, object, file, options)
+
+Add an object to the bucket.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object` {String} object key name
+- `file` {String} file string
+- `options` {Hash} optional parameters
+  - `expires` {String} expires time (milliseconds) for download, e.g.: 3600000
+  - `content_control` {String} cache control for download, e.g.: public, no-cache
+  - `content_encoding` {String} object content encoding for download
+  - `content_type` {String} object content type
+  - `content_disposition` {String} object name for download
+  - `encryption` {String} oss server side encryption `AES256`
+  - `acl` {String} object acl
+
+Success will return true
+
+#### .copy_object(bucket_name, object, old_bucket, old_object, options)
+
+To copy an existing object on OSS to form another object.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object` {String} object key name
+- `old_bucket` {String} existing object bucket
+- `old_object` {String} existing object
+- `options` {Hash} optional parameters
+  - `encryption` {String} oss server side encryption `AES256`
+  - `acl` {String} object acl header
+  - `if_none_match` {String} x-oss-copy-source-if-none-match header
+  - `if_match` {String} x-oss-copy-source-if-match header
+  - `if_unmodified_since` {String} x-oss-copy-source-if-unmodified-since header
+  - `if_modified_since` {String} x-oss-copy-source-if-modified-since header
+  - `metadata_directive` {String} x-oss-metadata-directive header
+
+Success will return Hash:
+
+- `last_modify` the object last modify time
+- `etag` the object etag
+
+#### .get_object(bucket_name, object, options)
+
+Get an object from the bucket.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object` {String} object key name
+- `options` {Hash} optional parameters
+  - `if_none_match` {String} x-oss-copy-source-if-none-match header
+  - `if_match` {String} x-oss-copy-source-if-match header
+  - `if_unmodified_since` {String} x-oss-copy-source-if-unmodified-since header
+  - `if_modified_since` {String} x-oss-copy-source-if-modified-since header
+  - `range` {String} http range header
+
+Success will return response object:
+
+```ruby
+object = @api.get_object('bucket_name', 'object_name')
+# show all file headers
+p object.headers
+
+# save file
+file = File.new('/path/to/save', 'w')
+file.puts object.body
+file.close
+```
+
+#### .append_object(bucket_name, object, file, position, options)
+
+Append file to a exist object.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object` {String} object key name
+- `file` {String} append file content
+- `position` {Integer} append file position
+- `options` {Hash} optional parameters
+
+Success will return Hash:
+
+- `hash_crc64ecma` {String} append object hash crc64
+- `next_append_position` {String} next append position
+
+#### .delete_object(bucket_name, object_name)
+
+Delete the object.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+
+Success will return true
+
+#### .delete_multiple_objects(bucket_name, objects)
+
+Delete multiple objects.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `objects` {Array} object names
+
+Success will return success deleted object names
+
+#### .head_object(bucket_name, object_name, options)
+
+Head an object and get the meta info.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `options` {Hash} optional parameters
+  - `if_none_match` {String} x-oss-copy-source-if-none-match header
+  - `if_match` {String} x-oss-copy-source-if-match header
+  - `if_unmodified_since` {String} x-oss-copy-source-if-unmodified-since header
+  - `if_modified_since` {String} x-oss-copy-source-if-modified-since header
+
+Success will return response headers
+
+#### .put_object_acl(bucket_name, object_name, acl)
+
+Set the object ACL.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `acl` {String} ACL control header
+
+Success will return true
+
+#### .get_object_acl(bucket_name, object_name)
+
+Get the object ACL.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+
+Success will return Hash:
+
+- `grant` {String} acl settings string
+- `owner` {Hash} object owner, including `id` and `display_name`
+
+#### .post_object(bucket_name, key, options)
+
+Create form post upload parameters.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `key` form upload key
+- `options` [Form field](https://docs.aliyun.com/en?spm=5176.383663.278239.8.BZrDTK#/pub/oss_en_us/api-reference/object&PostObject)
+
+return form post need parameters including `OSSAccessKeyId` `Signature`
+
+### Multipart Upload Operations
+Class `Oss::Multipart`
+
+#### .initiate_multipart_upload(bucket_name, object_name, options)
+
+The Initiate Multipart Upload interface must be called to notify OSS that a Multipart Upload event should be initiated before data transfer starts in the Multipart Upload mode. This interface will then return a globally unique Upload ID created by OSS to identify the Multipart Upload event. With the ID users can initiate related operations including stopping Multipart Upload, querying Multipart Upload, etc.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `options` {Hash} optional parameters
+  - `expires` {String} expires time (milliseconds) for download, e.g.: 3600000
+  - `content_control` {String} cache control for download, e.g.: public, no-cache
+  - `content_encoding` {String} object content encoding for download
+  - `content_disposition` {String} object name for download
+  - `encryption` {String} oss server side encryption `AES256`
+  
+Success will return Hash:
+- `bucket` {String} bucket name
+- `key` {String} key
+- `upload_id` {String} upload_id
+
+#### .upload_part(bucket_name, object_name, upload_id, file, part_number, options)
+
+After a Multipart Upload is initialized, data can be uploaded by part according to the specified Object name and Upload ID. Each part uploaded has an identification number (Part number, range: 1-10,000).
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `upload_id` {String} upload id
+- `part_number` {Integer} upload part number
+- `file` {String} file content
+- `options` {Hash} optional parameters
+
+Success will return Hash:
+- `etag` {String} part etag
+- `part_number` {String} part_number
+
+#### .upload_part_copy(bucket_name, object_name, upload_id, old_bucket, old_object, part_number, options)
+
+The interface Upload Part Copy is used to upload a Part data by copying the data from an existing Object.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `upload_id` {String} upload id
+- `old_bucket` {String} exist source bucket name
+- `old_object` {String} exist source object name
+- `part_number` {Integer} upload part number
+- `options` {Hash} optional parameters
+  - `if_none_match` {String} x-oss-copy-source-if-none-match header
+  - `if_match` {String} x-oss-copy-source-if-match header
+  - `if_unmodified_since` {String} x-oss-copy-source-if-unmodified-since header
+  - `copy_source_begin` {Integer} copy source begin byte
+  - `copy_source_end` {Integer} copy source end byte
+  
+Success will return Hash:
+- `etag` {String} part etag
+- `last_modify` {String} object last modify time
+
+#### .complete_multipart_upload(bucket_name, object_name, upload_id, parts)
+
+After all the Part data are uploaded, the API of Complete Multipart Upload must be called to complete the Multipart Upload of the entire file.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `upload_id` {String} upload id
+- `parts` {Array} uploaded parts Hash including `part_number` `etag`
+
+Success will return Hash:
+- `location` {String} storage location
+- `bucket` {String} bucket name
+- `key` {String} object key
+- `etag` {String} object etag
+
+#### .abort_multipart_upload(bucket_name, object_name, upload_id)
+
+This interface can be used to abort a Multipart Upload event according to the corresponding Upload ID offered by the user. 
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `upload_id` {String} upload id
+
+Success will return true
+
+#### .list_multipart_upload(bucket_name, options)
+
+This interface can list all Multipart Upload events under execution, which means all the events initialized but neither completed nor aborted. 
+
+parameters:
+- `bucket_name` {String} bucket name
+- `upload_id` {String} upload id
+- `options` {Hash} optional parameters
+  - `delimiter` {string} A character for grouping the names of Objects. 
+  - `prefix` {string} search object using `prefix` key
+  - `key_marker` {string} Used together with the upload-id-marker parameter to specify the initial position of returned results
+  - `max_uploads` {String} max uploads, default is `100`, limit to `1000`
+  - `upload-id-marker` {String} Used together with the key-marker parameter to specify the initial position of return results.
+  
+Success will return the class object, use chain method get response params.
+
+- `.uploads`
+return uploads Array including Hash:
+- `key` {String} upload key
+- `upload_id` {String} upload id
+- `initiated` {String} initiated time
+
+#### .list_parts(bucket_name, object_name, options)
+
+The interface List Parts can be used to list all Parts corresponding to a specified Upload ID which have been successfully uploaded.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `options` {Hash} optional parameters
+  - `uploadId` {String} search upload id
+  - `max_parts` {String} search max parts
+  - `part_number_marker` {String} search part number
+
+Success will return the class object, use chain method get response params.
+
+- `.parts`
+return parts Array including Hash:
+- `part_number` {String} part number
+- `last_modified` {String} last modified time
+- `etag` {String} part etag
+- `size` {String} part size
+
+### CORS (Cross-Origin Resource Sharing) Operations
+Class `Oss::Cors`
+
+#### .put_bucket_cors(bucket_name, rules)
+
+The operation Put Bucket cors will set a CORS rule on a specified bucket. If a rule is already existent, the original rule will be overlaid.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `rules` {Array} rules array e.g. `[[{key: 'AllowedOrigin', value: '*'}, {key: 'AllowedMethod', value: 'GET'}], [{key: 'AllowedOrigin', value: 'http://www.a.com'}, {key: 'AllowedMethod', value: 'PUT'}]]`
+
+Success will return true
+
+#### .get_bucket_cors(bucket_name)
+
+The operation of Get Bucket cors operation is used to get the current CORS rules in the specified Bucket.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return rules Array
+
+#### .delete_bucket_cors(bucket_name)
+
+The Delete Bucket cors operation is used to disable the CORS function corresponding to the specified Bucket and remove all the rules.
+
+parameters:
+- `bucket_name` {String} bucket name
+
+Success will return true
+
+#### .option_object(bucket_name, object_name, origin, request_method, request_headers)
+
+Before sending the cross-origin request, the browser will first send a preflight request (OPTIONS) with specific source origin, HTTP method, and header information to OSS so that it can decide whether to send the real request.
+
+parameters:
+- `bucket_name` {String} bucket name
+- `object_name` {String} object name
+- `origin` {String} Origin header
+- `request_method` {String} Access-Control-Request-Method	header
+- `request_headers` {String} Access-Control-Request-Headers header
+
+Success will return response headers
+
 ## License
 
 The gem is available as open source under the terms of the [Apache 2.0 License](http://opensource.org/licenses/Apache-2.0).

data/lib/oss/version.rb

@@ -1,3 +1,3 @@
 module Oss
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oss
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - RaymondChou