README.md

Microsoft Azure Storage Blob Client Library for Ruby

• Master:
• Dev:

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

Supported Ruby Versions

• Ruby 2.3 to 2.7

Note:

• x64 Ruby for Windows is known to have some compatibility issues.
• azure-storage-blob depends on gem nokogiri.

Getting Started

Install the rubygem package

You can install the azure storage blob rubygem package directly.

gem install azure-storage-blob

Setup Connection

You can use this Client Library against the Microsoft Azure Storage Blob 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
2. via environment variables

Via Code

• Against Microsoft Azure Services in the cloud

  require 'azure/storage/blob'

  # Setup a specific instance of an Azure::Storage::Blob::BlobService
  blob_client = Azure::Storage::Blob::BlobService.create(storage_account_name: <your account name>, storage_access_key: <your access key>)

  # Or create a client and initialize with it.
  require 'azure/storage/common'
  common_client = Azure::Storage::Common::Client.create(storage_account_name: <your account name>, storage_access_key: <your access key>)
  blob_client = Azure::Storage::Blob::BlobService.new(client: common_client)

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

• Against local Emulator (Windows Only)

  require 'azure/storage/blob'
  client = Azure::Storage::Blob::BlobService.create_development

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

Via Environment Variables

• Against Microsoft Azure Storage Blob Services in the cloud

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

• Against local Emulator (Windows Only)

  export EMULATED = true

• SSL Certificate File if having issues with ssl peer verification

  SSL_CERT_FILE=<path to *.pem>

Usage

Usage

# Require the azure storage blob rubygem
require 'azure/storage/blob'

# Setup a specific instance of an Azure::Storage::Blob::BlobService
client = Azure::Storage::Blob::BlobService.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::Blob::BlobService.create(storage_blob_host: "https://youraccountname.blob.core.windows.net")

# Add retry filter to the service object
require "azure/storage/common"
client.with_filter(Azure::Storage::Common::Core::Filter::ExponentialRetryPolicyFilter.new)

# Create a container
container = client.create_container('test-container')

# Upload a Blob
content = ::File.open('test.jpg', 'rb') { |file| file.read }
client.create_block_blob(container.name, 'image-blob', content)

# List containers
client.list_containers()

# List Blobs
client.list_blobs(container.name)

# Download a Blob
blob, content = client.get_blob(container.name, 'image-blob')
::File.open('download.png', 'wb') {|f| f.write(content)}

# Delete a Blob
client.delete_blob(container.name, 'image-blob')

Access Token

Please refer to the below links for obtaining an access token:

• Authenticate with Azure Active Directory
• Getting a MSI access token

require "azure/storage/common"

access_token = <your initial access token>

# Creating an instance of `Azure::Storage::Common::Core::TokenCredential`
token_credential = Azure::Storage::Common::Core::TokenCredential.new access_token
token_signer = Azure::Storage::Common::Core::Auth::TokenSigner.new token_credential
blob_token_client = Azure::Storage::Blob::BlobService.new(storage_account_name: <your_account_name>, signer: token_signer)

# Refresh internal is 50 minutes
refresh_interval = 50 * 60
# The user-defined thread that renews the access token
cancelled = false
renew_token = Thread.new do
  Thread.stop
  while !cancelled
    sleep(refresh_interval)

    # Renew the access token here

    # Update the access token to the credential
    token_credential.renew_token <new_access_token>
  end
end
sleep 0.1 while renew_token.status != 'sleep'
renew_token.run

# Call blob client functions as usaual

Customize the user-agent

You can customize the user-agent string by setting your user agent prefix when creating the service client.

# Require the azure storage blob rubygem
require "azure/storage/blob"

# Setup a specific instance of an Azure::Storage::Client with :user_agent_prefix option
client = Azure::Storage::Blob::BlobService.create(storage_account_name: <your account name>, storage_access_key: <your access key>, user_agent_prefix: <your application name>)

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.