Quickstart: Azure Blob Storage client library for Ruby

Article
12/04/2020

Learn how to use Ruby to create, download, and list blobs in a container in Microsoft Azure Blob Storage.

Prerequisites

To access Azure Storage, you'll need an Azure subscription. If you don't already have a subscription, create a free account before you begin.

All access to Azure Storage takes place through a storage account. For this quickstart, create a storage account using the Azure portal, Azure PowerShell, or Azure CLI. For help creating a storage account, see Create a storage account.

Make sure you have the following additional prerequisites installed:

Ruby
Azure Storage client library for Ruby, using the RubyGem package:
```
gem install azure-storage-blob
```

Download the sample application

The sample application used in this quickstart is a basic Ruby application.

Use Git to download a copy of the application to your development environment. This command clones the repository to your local machine:

git clone https://github.com/Azure-Samples/storage-blobs-ruby-quickstart.git

Navigate to the storage-blobs-ruby-quickstart folder, and open the example.rb file in your code editor.

Copy your credentials from the Azure portal

The sample application needs to authorize access to your storage account. Provide your storage account credentials to the application in the form of a connection string. To view your storage account credentials:

In to the Azure portal go to your storage account.
In the Settings section of the storage account overview, select Access keys to display your account access keys and connection string.
Note the name of your storage account, which you'll need for authorization.
Find the Key value under key1, and select Copy to copy the account key.

Configure your storage connection string

Provide your storage account name and account key to create a BlobService instance for your application.

The following code in the example.rb file instantiates a new BlobService object. Replace the accountname and accountkey values with your account name and key.

# Create a BlobService object
account_name = "accountname"
account_key = "accountkey"

blob_client = Azure::Storage::Blob::BlobService.create(
    storage_account_name: account_name,
    storage_access_key: account_key
)

Run the sample

The sample creates a container in Blob Storage, creates a new blob in the container, lists the blobs in the container, and downloads the blob to a local file.

Run the sample. Here is an example of the output from running the application:

C:\azure-samples\storage-blobs-ruby-quickstart> ruby example.rb

Creating a container: quickstartblobs18cd9ec0-f4ac-4688-a979-75c31a70503e

Creating blob: QuickStart_6f8f29a8-879a-41fb-9db2-0b8595180728.txt

List blobs in the container following continuation token
        Blob name: QuickStart_6f8f29a8-879a-41fb-9db2-0b8595180728.txt

Downloading blob to C:/Users/azureuser/Documents/QuickStart_6f8f29a8-879a-41fb-9db2-0b8595180728.txt

Paused, press the Enter key to delete resources created by the sample and exit the application

When you press Enter to continue, the sample program deletes the storage container and the local file. Before you continue, check your Documents folder for the downloaded file.

You can also use Azure Storage Explorer to view the files in your storage account. Azure Storage Explorer is a free cross-platform tool that allows you to access your storage account information.

After you've verified the files, press the Enter key to delete the test files and end the demo. Open the example.rb file to look at the code.

Understand the sample code

Next, we walk through the sample code so you can understand how it works.

Get references to the storage objects

The first thing to do is create instances of the objects used to access and manage Blob Storage. These objects build on each other. Each is used by the next one in the list.

Create an instance of the Azure storage BlobService object to set up connection credentials.
Create the Container object, which represents the container you're accessing. Containers are used to organize your blobs like you use folders on your computer to organize your files.

Once you have the container object, you can create a Block blob object that points to a specific blob in which you're interested. Use the Block object to create, download, and copy blobs.

Important

Container names must be lowercase. For more information about container and blob names, see Naming and Referencing Containers, Blobs, and Metadata.

The following example code:

Creates a new container
Sets permissions on the container so the blobs are public. The container is called quickstartblobs with a unique ID appended.

# Create a container
container_name = "quickstartblobs" + SecureRandom.uuid
puts "\nCreating a container: " + container_name
container = blob_client.create_container(container_name)

# Set the permission so the blobs are public
blob_client.set_container_acl(container_name, "container")

Create a blob in the container

Blob Storage supports block blobs, append blobs, and page blobs. To create a blob, call the create_block_blob method passing in the data for the blob.

The following example creates a blob called QuickStart_ with a unique ID and a .txt file extension in the container created earlier.

# Create a new block blob containing 'Hello, World!'
blob_name = "QuickStart_" + SecureRandom.uuid + ".txt"
blob_data = "Hello, World!"
puts "\nCreating blob: " + blob_name
blob_client.create_block_blob(container.name, blob_name, blob_data)

Block blobs can be as large as 4.7 TB, and can be anything from spreadsheets to large video files. Page blobs are primarily used for the VHD files that back IaaS virtual machines. Append blobs are commonly used for logging, such as when you want to write to a file and then keep adding more information.

List the blobs in a container

Get a list of files in the container using the list_blobs method. The following code retrieves the list of blobs, then displays their names.

# List the blobs in the container
puts "\nList blobs in the container following continuation token"
nextMarker = nil
loop do
    blobs = blob_client.list_blobs(container_name, { marker: nextMarker })
    blobs.each do |blob|
        puts "\tBlob name: #{blob.name}"
    end
    nextMarker = blobs.continuation_token
    break unless nextMarker && !nextMarker.empty?
end

Download a blob

Download a blob to your local disk using the get_blob method. The following code downloads the blob created in a previous section.

# Download the blob

# Set the path to the local folder for downloading
if(is_windows)
    local_path = File.expand_path("~/Documents")
else 
    local_path = File.expand_path("~/")
end

# Create the full path to the downloaded file
full_path_to_file = File.join(local_path, blob_name)

puts "\nDownloading blob to " + full_path_to_file
blob, content = blob_client.get_blob(container_name, blob_name)
File.open(full_path_to_file,"wb") {|f| f.write(content)}

Clean up resources

If a blob is no longer needed, use delete_blob to remove it. Delete an entire container using the delete_container method. Deleting a container also deletes any blobs stored in the container.

# Clean up resources, including the container and the downloaded file
blob_client.delete_container(container_name)
File.delete(full_path_to_file)

Resources for developing Ruby applications with blobs

See these additional resources for Ruby development:

View and download the Ruby client library source code for Azure Storage on GitHub.
Explore Azure samples written using the Ruby client library.
Sample: Getting Started with Azure Storage in Ruby

Next steps

In this quickstart, you learned how to transfer files between Azure Blob Storage and a local disk by using Ruby. To learn more about working with Blob Storage, continue to the Storage account overview.

Storage account overview

For more information about the Storage Explorer and Blobs, see Manage Azure Blob Storage resources with Storage Explorer.