Crate azure_storage_blob

Expand description

§Azure Storage Blob client library for Rust

Azure Blob storage is Microsoft’s object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data.

Source code | Package (crates.io) | API reference documentation | REST API documentation | Product documentation

§Getting started

§Install the package

Install the Azure Storage Blob client library for Rust with cargo:

cargo add azure_storage_blob

§Prerequisites

You must have an Azure subscription and an Azure storage account to use this package.

§Create a storage account

If you wish to create a new storage account, you can use the Azure Portal, Azure PowerShell, or Azure CLI:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

§Authenticate the client

In order to interact with the Azure Blob Storage service, you’ll need to create an instance of a client, BlobClient, BlobContainerClient, or BlobServiceClient. BlobServiceClient is the recommended entry point. Construct it once using BlobServiceClient::new(), then call BlobServiceClient::blob_container_client() or BlobServiceClient::blob_client() to get a BlobContainerClient or BlobClient respectively. If you already have a fully-formed (for example, SAS-scoped) URL for a single container or blob, call BlobContainerClient::new() or BlobClient::new() with that URL directly instead.

The Azure Identity library makes it easy to add Microsoft Entra ID support for authenticating Azure SDK clients with their corresponding Azure services:

use azure_core::http::Url;
use azure_storage_blob::BlobServiceClient;
use azure_identity::DeveloperToolsCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a BlobServiceClient that will authenticate through Microsoft Entra ID
    let credential = DeveloperToolsCredential::new(None)?;
    let service_url = Url::parse("https://<storage_account_name>.blob.core.windows.net/")?;
    let service_client = BlobServiceClient::new(
        service_url,
        Some(credential),
        None,
    )?;

    // Derive container and blob clients by name.
    let container_client = service_client.blob_container_client("<container_name>");
    let blob_client = container_client.blob_client("<blob_name>");
    Ok(())
}

§Permissions

You may need to specify RBAC roles to access Blob Storage via Microsoft Entra ID. Please see Assign an Azure role for access to blob data for more details.

§Examples

You can find executable examples for all major SDK functions in:

blob_hello_world.rs - Getting started: create a container, upload and download a blob
blob_client.rs - Blob-level operations: exists, metadata, index tags, access tier
blob_container_client.rs - Container-level operations: metadata, list blobs with continuation, access policies
blob_service_client.rs - Service-level operations: list containers, service properties, statistics
block_blob_client.rs - Block blob operations: staged block upload, copy from URL
append_blob_client.rs - Append blob operations: create, append blocks, seal
page_blob_client.rs - Page blob operations: create, upload/clear pages, list page ranges, resize
blob_storage_upload_file.rs - Upload a local file with streaming support for large files
blob_storage_logging.rs - Logging and OpenTelemetry distributed tracing
storage_error.rs - Structured error handling with StorageError

§Upload a blob

use azure_core::http::{RequestContent, Url};
use azure_storage_blob::BlobServiceClient;
use azure_identity::DeveloperToolsCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DeveloperToolsCredential::new(None)?;
    let service_url = Url::parse("https://<storage_account_name>.blob.core.windows.net/")?;
    let service_client = BlobServiceClient::new(service_url, Some(credential), None)?;
    let blob_client = service_client.blob_client("<container_name>", "<blob_name>");

    let data = b"hello world";
    blob_client
        .upload(
            RequestContent::from(data.to_vec()), // Data
            None,                                // Upload Options
        )
        .await?;
    Ok(())
}

§Download a blob

use azure_core::http::Url;
use azure_storage_blob::BlobServiceClient;
use azure_identity::DeveloperToolsCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DeveloperToolsCredential::new(None)?;
    let service_url = Url::parse("https://<storage_account_name>.blob.core.windows.net/")?;
    let service_client = BlobServiceClient::new(service_url, Some(credential), None)?;
    let blob_client = service_client.blob_client("<container_name>", "<blob_name>");

    let response = blob_client.download(None).await?;
    let data = String::from_utf8(response.body.collect().await?.into())?;
    println!("Downloaded: {data}");
    Ok(())
}

§Remarks

§Automatic decompression with custom HTTP transports

By default, all storage clients create an HTTP transport with automatic decompression disabled, which is required for partitioned (multi-part) downloads to work correctly. If you set a custom transport in client options (e.g., a reqwest::Client with gzip enabled) without disabling automatic decompression, partitioned downloads via BlobClient::download may not work correctly. If you need to provide a custom transport, disable automatic decompression to be consistent with default SDK behavior.

§Next Steps

§Provide Feedback

If you encounter bugs or have suggestions, open an issue.

§Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You’ll only need to do this once across all repos using our CLA.

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.

Re-exports§

pub use clients::*;

Modules§

clients: Clients used to communicate with Azure Blob Storage.
models: Model types for Azure Blob Storage.
stream: Stream implementations for Azure Blob Storage.

Structs§

StorageError: Represents an error response from Azure Storage services.

Functions§

format_filter_expression: Takes in a HashMap of tag key-value pairs and converts them to a filter expression for use with BlobServiceClient::find_blobs_by_tags() or BlobContainerClient::find_blobs_by_tags().

Type Aliases§

Result: A specialized Result type for Azure Storage Blob operations.