<commit_before># Aliyun::Oss

Ruby gem for [Aliyun Open Storage Service (OSS)][1]. This gem implemented API from [references of Aliyun OSS-API][2].

## Table of Contents

* [Installation](#installation)
* [Usage](#usage)
  * [Load Access Key ID and Access Key Secrete](#load)
  * [Using Bucket API](#highlevel)
    * [List Buckets](#listbuckets)
	* [Create a Bucket](#newbucket)
	* [List Files In Bucket](#listfiles)
	* [Upload a File to Bucket](#uploadfile)
	* [Download a File from Bucket](#downloadfile)
	* [Share a File in Bucket](#sharefile)
	* [Delete a File in Bucket](#deletefile)
	* [Upload a Large File in Multipart Way](#uploadlargefile)
	* [Delete a bucket](#deletebucket)
	* [Enable/Disable Logging for bucket](#logging)
  * [Using Primitive API](#lowlevel)
* [Test](#test)
* [Contribute](#contribute)

## <a name="installation"></a>Installation

Add this line to your application's Gemfile:

```ruby
gem 'aliyunoss'
```

And then execute:

```ruby
$ bundle
```

Or install it yourself as:

```ruby
$ gem install aliyunoss
```

## <a name="usage"></a>Usage

This gem provides Bucket API which are built around class Bucket and Primitive API which are wrappers for [OSS API][2]. Most of time using Bucket API is OK except you find OSS API that I didn't implement.

### <a name="load"></a>Load Access Key ID and Access Key Secret

Specify you access key and access secret before calling methods provided in this gem:

```ruby
Aliyun::Oss::configure(:access_key_id => 'access key id from aliyun', :access_key_secret => 'access secret from aliyun')
```
	
When using this gem in a rails project, you can create a file named 'aliyunoss_key.rb' in RAILS\_ROOT/config/initializers, whose content is: 

```ruby
Aliyun::Oss::configure(:access_key_id => 'access key id from aliyun', :access_key_secret => 'access secret from aliyun')
```
	
Then you can use the following APIs anywhere.

### <a name="highlevel"></a>Bucket API

Bucket API are built around class Bucket. You create a new bucket, and upload, download or delete files in it. When needed, responses are parsed to array, hash or object etc, thus more meaningful. Exceptions will be raised when request failed.

```ruby
# Create a bucket in OSS server
bucket = Aliyun::Oss::Bucket.create('aliyun-oss-gem-api-test','oss-cn-hangzhou')
	
# Upload a file
filename = '/some/file'
bucket.upload( IO.read(filename) )
	
# List all files in this bucket, returns a Hash array containing files info
files = bucket.list_files
	
# Download a file, returns raw data
data = bucket.download( '/some/path' )
```
	
#### <a name="listbuckets"></a>List all buckets

After correctly configuring your access key and secret, you can list all buckets:

```ruby
Aliyun::Oss::Bucket.all
```

The result is a Bucket array. Class Bucket has some simple attributes :

```ruby
class Bucket
  attr_accessor :location, :name, :creation_date, :domain, :extranet_endpoint, :intranet_endpoint
  # ...
end
```

#### <a name="newbucket"></a>Create a new bucket

You can create a new bucket using class method *create* of Bucket:

```ruby
bucket = Aliyun::Oss::Bucket.create(bucket_name, bucket_location)
```
	
Where *bucket_name* is a string, and *bucket_location* is an optional string parameter which defaults to 'oss-cn-hangzhou'. Other available bucket locations can be referenced [here][5]. This method return a new Bucket instance if success.

#### <a name="listfiles"></a>List all files in an bucket

You can list all files in an bucket using instance method *list\_files* of a bucket:
<commit_msg>Added description for opening a bucket<commit_after># Aliyun::Oss

Ruby gem for [Aliyun Open Storage Service (OSS)][1]. This gem implemented API from [references of Aliyun OSS-API][2].

## Table of Contents

* [Installation](#installation)
* [Usage](#usage)
  * [Load Access Key ID and Access Key Secrete](#load)
  * [Using Bucket API](#highlevel)
    * [List Buckets](#listbuckets)
	* [Create a Bucket](#newbucket)
	* [Open a Bucket](#openbucket)
	* [List Files In Bucket](#listfiles)
	* [Upload a File to Bucket](#uploadfile)
	* [Download a File from Bucket](#downloadfile)
	* [Share a File in Bucket](#sharefile)
	* [Delete a File in Bucket](#deletefile)
	* [Upload a Large File in Multipart Way](#uploadlargefile)
	* [Delete a bucket](#deletebucket)
	* [Enable/Disable Logging for bucket](#logging)
  * [Using Primitive API](#lowlevel)
* [Test](#test)
* [Contribute](#contribute)

## <a name="installation"></a>Installation

Add this line to your application's Gemfile:

```ruby
gem 'aliyunoss'
```

And then execute:

```ruby
$ bundle
```

Or install it yourself as:

```ruby
$ gem install aliyunoss
```

## <a name="usage"></a>Usage

This gem provides Bucket API which are built around class Bucket and Primitive API which are wrappers for [OSS API][2]. Most of time using Bucket API is OK except you find OSS API that I didn't implement.

### <a name="load"></a>Load Access Key ID and Access Key Secret

Specify you access key and access secret before calling methods provided in this gem:

```ruby
Aliyun::Oss::configure(:access_key_id => 'access key id from aliyun', :access_key_secret => 'access secret from aliyun')
```
	
When using this gem in a rails project, you can create a file named 'aliyunoss_key.rb' in RAILS\_ROOT/config/initializers, whose content is: 

```ruby
Aliyun::Oss::configure(:access_key_id => 'access key id from aliyun', :access_key_secret => 'access secret from aliyun')
```
	
Then you can use the following APIs anywhere.

### <a name="highlevel"></a>Bucket API

Bucket API are built around class Bucket. You create a new bucket, and upload, download or delete files in it. When needed, responses are parsed to array, hash or object etc, thus more meaningful. Exceptions will be raised when request failed.

```ruby
# Create a bucket in OSS server
bucket = Aliyun::Oss::Bucket.create('aliyun-oss-gem-api-test','oss-cn-hangzhou')
	
# Upload a file
filename = '/some/file'
bucket.upload( IO.read(filename) )
	
# List all files in this bucket, returns a Hash array containing files info
files = bucket.list_files
	
# Download a file, returns raw data
data = bucket.download( '/some/path' )
```
	
#### <a name="listbuckets"></a>List all buckets

After correctly configuring your access key and secret, you can list all buckets:

```ruby
Aliyun::Oss::Bucket.all
```

The result is a Bucket array. Class Bucket has some simple attributes :

```ruby
class Bucket
  attr_accessor :location, :name, :creation_date, :domain, :extranet_endpoint, :intranet_endpoint
  # ...
end
```

#### <a name="newbucket"></a>Create a new bucket

You can create a new bucket using class method *create* of Bucket:

```ruby
bucket = Aliyun::Oss::Bucket.create(bucket_name, bucket_location)
```
	
Where *bucket_name* is a string, and *bucket_location* is an optional string parameter which defaults to 'oss-cn-hangzhou'. Other available bucket locations can be referenced [here][5]. This method return a new Bucket instance if success.

#### <a name="openbucket"></a>Open a bucket

There is no such opeartion as opening a bucket, but you can build a Bucket class by:

```ruby
Aliyun::Oss::Bucket.new(name: 'bucket-name', location: 'oss-cn-beijing')
```

So you can continue to download or upload files using this Bucket instance.

#### <a name="listfiles"></a>List all files in an bucket

You can list all files in an bucket using instance method *list\_files* of a bucket:

{'fraction_non_alphanumeric': 0.12117123195250304, 'fraction_numerical': 0.001079476453919849, 'mean_word_length': 4.9296, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 41, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 11, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1385851', 'n_tokens_mistral': 2370, 'n_tokens_neox': 2225, 'n_words': 897}