Skip to content

Commit

Permalink
Merge pull request #109 from katmsft/split
Browse files Browse the repository at this point in the history 
Azure-storage-ruby 1.0.0 Release PR
  • Loading branch information
@vinjiang
vinjiang authored Jan 12, 2018
2 parents 381b179 + 54c9c9a commit b53d436
Show file tree
Hide file tree
Showing 221 changed files with 5,221 additions and 2,399 deletions.
2 changes: 2 additions & 0 deletions .travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ rvm:
- 2.0.0
- 2.1.6
- 2.2.2
- 2.4.1
- 2.5.0

before_install:
- gem install bundler
Expand Down
2 changes: 2 additions & 0 deletions BreakingChanges.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
**Note: This BreakingChanges.md file is deprecated after version 0.15.0-preview, please refer to the BreakingChange.md in each package for future change logs.**

Tracking Breaking Changes in 0.14.0-preview

QUEUE
Expand Down
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ If you intend to contribute to the project, please make sure you've followed the
The Azure Storage development team uses Visual Studio Code so instructions will be tailored to that preference. However, any preferred IDE or other toolset should be usable.

### Install
* Ruby 1.9.3, 2.0, 2.1 or 2.2.
* Ruby 1.9.3 to 2.5.0.
* [Visual Studio Code](https://code.visualstudio.com/)

### Development Environment Setup
Expand Down Expand Up @@ -43,7 +43,7 @@ You can use the following commands to run:

* All the tests: ``rake test``. **This will run integration tests if you have .env file or env vars setup**
* Run storage suite of tests: ``rake test:unit``, ``rake test:integration``
* One particular test file: ``ruby -I"lib:test" "<path of the test file>"``
* One particular test file: ``ruby -I".\blob\lib;.\common\lib;.\table\lib;.\queue\lib;.\file\lib;test" "<path of the test file>"``

### Testing Features
As you develop a feature, you'll need to write tests to ensure quality. Your changes should be covered by both unit tests and integration tests. You should also run existing tests related to your change to address any unexpected breaks.
Expand All @@ -59,11 +59,11 @@ The following are the minimum requirements for any pull request that must be met
* You should strive to mimic the style with which we have written the library
* Clean, well-commented, well-designed code
* Try to limit the number of commits for a feature to 1-2. If you end up having too many we may ask you to squash your changes into fewer commits.
* [ChangeLog.md](ChangeLog.md) needs to be updated describing the new change
* ChangeLog.md in service module folders needs to be updated describing the new change
* Thoroughly test your feature

### Branching Policy
Changes should be based on the **dev** branch, not master as master is considered publicly released code. Each breaking change should be recorded in [BreakingChanges.md](BreakingChanges.md).
Changes should be based on the **dev** branch, not master as master is considered publicly released code. Each breaking change should be recorded in the corresponding BreakingChanges.md in service module folders. Note that [BreakingChanges.md](BreakingChanges.md) is deprecated after GA release.

### Adding Features for All Platforms
We strive to release each new feature for each of our environments at the same time. Therefore, we ask that all contributions be written for Ruby 1.9.3 and later.
Expand Down
2 changes: 2 additions & 0 deletions ChangeLog.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
**Note: This changelog is deprecated after version 0.15.0-preview, please refer to the ChangeLog.md in each package for future change logs.**

2017.11 - version 0.15.0-preview

ALL
Expand Down
16 changes: 12 additions & 4 deletions Gemfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,16 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#--------------------------------------------------------------------------
source "https://rubygems.org"
source "https://rubygems.org" do
gem "azure-core", "~> 0.1.13", :require => false
gem "nokogiri", "~> 1.6", ">= 1.6.8", :require => false

gemspec name: "azure-storage"

gem "coveralls", require: false
gem "dotenv", "~> 2.0", :require => false
gem "minitest", "~> 5", :require => false
gem "minitest-reporters", "~> 1", :require => false
gem "mocha", "~> 1.0", :require => false
gem "rake", "~> 10.0", :require => false
gem "timecop", "~> 0.7", :require => false
gem "yard", "~> 0.9", ">= 0.9.11", :require => false
gem "coveralls", require: false
end
302 changes: 9 additions & 293 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,307 +1,21 @@
# Microsoft Azure Storage Client Library for Ruby

[![Gem Version](https://badge.fury.io/rb/azure-storage.svg)](https://badge.fury.io/rb/azure-storage)
* Master: [![Master Build Status](https://travis-ci.org/Azure/azure-storage-ruby.svg?branch=master)](https://travis-ci.org/Azure/azure-storage-ruby/branches) [![Coverage Status](https://coveralls.io/repos/github/Azure/azure-storage-ruby/badge.svg?branch=master)](https://coveralls.io/github/Azure/azure-storage-ruby?branch=master)
* Dev: [![Dev Build Status](https://travis-ci.org/Azure/azure-storage-ruby.svg?branch=dev)](https://travis-ci.org/Azure/azure-storage-ruby/branches) [![Coverage Status](https://coveralls.io/repos/github/Azure/azure-storage-ruby/badge.svg?branch=dev)](https://coveralls.io/github/Azure/azure-storage-ruby?branch=dev)

This project provides a Ruby package that makes it easy to access and manage Microsoft Azure Storage Services.
This project provides Ruby packages that makes it easy to access and manage Microsoft Azure Storage Services.

# Library Features
# Library Packages

* [Blobs](#blobs)
* [Tables](#tables)
* [Queues](#queues)
* [Files](#files)

# Supported Ruby Versions

* Ruby 2.0
* Ruby 2.1
* Ruby 2.2
* [Blobs](https://github.com/azure/azure-storage-ruby/tree/master/blob)
* [Tables](https://github.com/azure/azure-storage-ruby/tree/master/table)
* [Queues](https://github.com/azure/azure-storage-ruby/tree/master/queue)
* [Files](https://github.com/azure/azure-storage-ruby/tree/master/file)

Note:

* x64 Ruby for Windows is known to have some compatibility issues.
* azure-storage depends on gem nokogiri. For Ruby version lower than 2.2, please install the compatible nokogiri before trying to install azure-storage.

# Getting Started

## Install the rubygem package

You can install the azure rubygem package directly.

```bash
gem install azure-storage --pre
```

## Setup Connection

You can use this SDK against the Microsoft Azure Storage Services in the cloud, or against the local Storage Emulator if you are on Windows.

There are two ways you can set up the connections:

1. [via code](#via-code)
2. [via environment variables](#via-environment-variables)

<a name="via-code"></a>
### Via Code
* Against Microsoft Azure Services in the cloud

```ruby

require 'azure/storage'

# Setup a specific instance of an Azure::Storage::Client
client = Azure::Storage::Client.create(:storage_account_name => 'your account name', :storage_access_key => 'your access key')

# Or create a client and store as a singleton
Azure::Storage.setup(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Then you can either call Azure::Storage.client.some_method or Azure::Storage.some_method to invoke a method on the Storage Client

# Configure a ca_cert.pem file if you are having issues with ssl peer verification
client.ca_file = './ca_file.pem'

```

* Against local Emulator (Windows Only)

```ruby

require 'azure/storage'
client = Azure::Storage::Client.create_development

# Or create by options and provide your own proxy_uri
client = Azure::Storage::Client.create(:use_development_storage => true, :development_storage_proxy_uri => 'your proxy uri')

```

<a name="via-environment-variables"></a>
### Via Environment Variables

* Against Microsoft Azure Storage Services in the cloud

```bash
export AZURE_STORAGE_ACCOUNT = <your azure storage account name>
export AZURE_STORAGE_ACCESS_KEY = <your azure storage access key>
```

* Against local Emulator (Windows Only)

```bash
export EMULATED = true
```

* [SSL Certificate File](https://gist.github.com/fnichol/867550) if having issues with ssl peer verification

```bash
SSL_CERT_FILE=<path to *.pem>
```

# Usage

<a name="blobs"></a>
## Blobs

```ruby
# Require the azure storage rubygem
require 'azure/storage'
# Setup a specific instance of an Azure::Storage::Client
client = Azure::Storage::Client.create(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Alternatively, create a client that can anonymously access public containers for read operations
client = Azure::Storage::Client.create(storage_blob_host: "https://youraccountname.blob.core.windows.net")
# Get an azure storage blob service object from a specific instance of an Azure::Storage::Client
blobs = client.blob_client
# Or setup the client as a singleton
Azure::Storage.setup(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Create an azure storage blob service object after you set up the credentials
blobs = Azure::Storage::Blob::BlobService.new
# Add retry filter to the service object
blobs.with_filter(Azure::Storage::Core::Filter::ExponentialRetryPolicyFilter.new)
# Create a container
container = blobs.create_container('test-container')
# Upload a Blob
content = ::File.open('test.jpg', 'rb') { |file| file.read }
blobs.create_block_blob(container.name, 'image-blob', content)
# List containers
blobs.list_containers()
# List Blobs
blobs.list_blobs(container.name)
# Download a Blob
blob, content = blobs.get_blob(container.name, 'image-blob')
::File.open('download.png', 'wb') {|f| f.write(content)}
# Delete a Blob
blobs.delete_blob(container.name, 'image-blob')
```
<a name="tables"></a>
## Tables
```ruby
# Require the azure storage rubygem
require 'azure/storage'
# Setup a specific instance of an Azure::Storage::Client
client = Azure::Storage::Client.create(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Get an azure storage table service object from a specific instance of an Azure::Storage::Client
tables = client.table_client
# Or setup the client as a singleton
Azure::Storage.setup(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Create an azure storage table service object after you set up the credentials
tables = Azure::Storage::Table::TableService.new
# Add retry filter to the service object
tables.with_filter(Azure::Storage::Core::Filter::ExponentialRetryPolicyFilter.new)
# Create a table
tables.create_table('testtable')
# Insert an entity
entity = { content: 'test entity', PartitionKey: 'test-partition-key', RowKey: '1' }
tables.insert_entity('testtable', entity)
# Get an entity
result = tables.get_entity('testtable', 'test-partition-key', '1')
# Update an entity
result.properties['content'] = 'test entity with updated content'
tables.update_entity(result.table, result.properties)
# Query entities
query = { :filter => "content eq 'test entity'" }
result, token = tables.query_entities('testtable', query)
# Delete an entity
tables.delete_entity('testtable', 'test-partition-key', '1')
# delete a table
tables.delete_table('testtable')
```
<a name="queues"></a>
## Queues
```ruby
# Require the azure storage rubygem
require 'azure/storage'
# Setup a specific instance of an Azure::Storage::Client
client = Azure::Storage::Client.create(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Get an azure storage queue service object from a specific instance of an Azure::Storage::Client
queues = client.queue_client
# Or setup the client as a singleton
Azure::Storage.setup(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Create an azure storage queue service object after you set up the credentials
queues = Azure::Storage::Queue::QueueService.new
# Add retry filter to the service object
queues.with_filter(Azure::Storage::Core::Filter::ExponentialRetryPolicyFilter.new)
# Create a queue
queues.create_queue('test-queue')
# Create a message
queues.create_message('test-queue', 'test message')
# Get one or more messages with setting the visibility timeout
result = queues.list_messages('test-queue', 30, { number_of_messages: 10 })
# Get one or more messages without setting the visibility timeout
result = queues.peek_messages('test-queue', { number_of_messages: 10 })
# Update a message
message = queues.list_messages('test-queue', 30)
pop_receipt, time_next_visible = queues.update_message('test-queue', message[0].id, message[0].pop_receipt, 'updated test message', 30)
# Delete a message
message = queues.list_messages('test-queue', 30)
queues.delete_message('test-queue', message[0].id, message[0].pop_receipt)
# Delete a queue
queues.delete_queue('test-queue')
```
<a name="files"></a>
## Files
```ruby
# Require the azure storage rubygem
require 'azure/storage'
# Setup a specific instance of an Azure::Storage::Client
client = Azure::Storage::Client.create(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Get an azure storage file service object from a specific instance of an Azure::Storage::Client
files = client.file_client
# Or setup the client as a singleton
Azure::Storage.setup(:storage_account_name => 'your account name', :storage_access_key => 'your access key')
# Create an azure storage file service object after you set up the credentials
files = Azure::Storage::File::FileService.new
# Add retry filter to the service object
files.with_filter(Azure::Storage::Core::Filter::ExponentialRetryPolicyFilter.new)
# Create a share
share = files.create_share('test-share')
# Create a directory
directory = files.create_directory(share.name, 'test-directory')
# Create a file and update the file content
content = ::File.open('test.jpg', 'rb') { |file| file.read }
file = files.create_file(share.name, directory.name, 'test-file', content.size)
files.put_file_range(share.name, directory.name, file.name, 0, content.size - 1, content)
# List shares
files.list_shares()
# List directories and files
files.list_directories_and_files(share.name, directory.name)
# Download a File
file, content = files.get_file(share.name, directory.name, file.name)
::File.open('download.png', 'wb') {|f| f.write(content)}
# Delete a File
files.delete_file(share.name, directory.name, file.name)
```
<a name="Customize the user-agent"></a>
## Customize the user-agent
You can customize the user-agent string by setting your user agent prefix when creating the service client.
```ruby
# Require the azure storage rubygem
require "azure/storage"
# Setup a specific instance of an Azure::Storage::Client with :user_agent_prefix option
client = Azure::Storage::Client.create(:storage_account_name => "your account name", :storage_access_key => "your access key", :user_agent_prefix => "your application name")
```
* Each service gems depends on gem nokogiri. For Ruby version lower than 2.2, please install the compatible nokogiri before trying to install azure-storage.

# Getting Started for Contributors

Expand All @@ -320,6 +34,8 @@ If you encounter any bugs with the library please file an issue in the [Issues](
* [Azure Storage Client Library for Python](http://github.com/azure/azure-storage-python)
* [Azure Storage Client Library for Ruby](http://github.com/azure/azure-storage-ruby)
* [Azure Storage Client Library for C++](http://github.com/azure/azure-storage-cpp)
* [Azure Storage Client Library for PHP](http://github.com/azure/azure-storage-php)
* [Azure Storage Blob Client Library for Go](https://github.com/Azure/azure-storage-blob-go)
* [Azure Storage Client Library for iOS](http://github.com/azure/azure-storage-ios)
* [Azure Storage Client Library for Android](http://github.com/azure/azure-storage-android)
* [Azure Storage Data Movement Library](https://github.com/Azure/azure-storage-net-data-movement)
Expand Down
Loading

0 comments on commit b53d436

Please sign in to comment.