azure-storage-blob-rust

# Azure Blob Storage library for Rust Client library for Azure Blob Storage — upload, download, and manage blobs and containers. Use this skill when: - An app needs to upload or download blobs from Azure Storage in Rust - You need to create or manage blob containers - You need to list blobs with pagination - You need RBAC-based auth for blob operations > **IMPORTANT:** Only use the official `azure_storage_blob` crate published by the [azure-sdk](https://crates.io/users/azure-sdk) crates.io user. Do NOT use the unofficial `azure_storage`, `azure_storage_blobs`, or `azure_sdk_for_rust` community crates. Official crates use underscores in names and none have version 0.21.0. ## Installation ```sh cargo add azure_storage_blob azure_identity azure_core tokio futures ``` > If your code uses `azure_core` types directly (for example, `azure_core::http::Url` or `azure_core::http::RequestContent`), add `azure_core` to `Cargo.toml`. If you only use `azure_storage_blob` re-exports, direct `azure_core` dependency is optional. ## Environment Variables ```bash AZURE_STORAGE_ENDPOINT=https://<account>.blob.core.windows.net/ # Required for all operations ``` ## Authentication ```rust use azure_core::http::Url; use azure_identity::DeveloperToolsCredential; use azure_storage_blob::BlobServiceClient; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { // Local dev: DeveloperToolsCredential. Production: use ManagedIdentityCredential. 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(()) } ``` ## Client Types | Client | Purpose | | --------------------- | ----------------------------------------- | | `BlobServiceClient` | Account-level operations, list containers | | `BlobContainerClient` | Container operations, list blobs | | `BlobClient` | Individual blob operations | ## Core Workflow ### Upload Blob ```rust use azure_core::http::{RequestContent, Url}; use azure_identity::DeveloperToolsCredential; use azure_storage_blob::BlobServiceClient; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { // Local dev: DeveloperToolsCredential. Production: use ManagedIdentityCredential. 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()), None).await?; Ok(()) } ``` ### Download Blob / Get Properties ```rust // Get blob properties let props = blob_client.get_properties(None).await?; // Download blob content let response = blob_client.download(None).await?; let content = String::from_utf8(response.body.collect().await?.into())?; ``` ### Delete Blob ```rust blob_client.delete(None).await?; ``` ### Container Operations ```rust use azure_core::http::Url; use azure_identity::DeveloperToolsCredential; use azure_storage_blob::BlobServiceClient; use futures::TryStreamExt as _; 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 container_client = service_client.blob_container_client("<container_name>"); // Create container container_client.create(None).await?; // List blobs (Pager<T> — iterate items directly) let mut pager = container_client.list_blobs(None)?; while let Some(blob) = pager.try_next().await? { println!("Blob: {:?}", blob.name); } ``` ## Error Handling Use `StorageError` for programmatic access to storage-specific error codes: ```rust use azure_core::error::ErrorKind; use azure_storage_blob::StorageError; use azure_storage_blob::models::StorageErrorCode; let result = blob_client.download(None).await; match result { Ok(response) => { let content: Vec<u8> = response.body.collect().await?.into(); println!("Downloaded {} bytes", content.len()); } Err(error) => { if matches!(error.kind(), ErrorKind::HttpResponse { .. }) { // Convert to StorageError for programmatic access let storage_error: StorageError = error.try_into()?; println!("HTTP Status: {}", storage_error.status_code); if let Some(error_code) = &storage_error.error_code { match error_code { StorageErrorCode::BlobNotFound => { println!("The blob does not exist."); } StorageErrorCode::ContainerNotFound => { println!("The container does not exist."); } StorageErrorCode::AuthorizationFailure => { println!("Authorization failed. Check RBAC roles."); } _ => println!("Storage error: {error_code}"), } } if let Some(request_id) = &storage_error.request_id { println!("Request ID (for Azure support): {request_id}"); } } else { println!("Non-HTTP error: {:?}", error); } } } ``` > **Note:** `StorageError::try_into` requires an owned error object — it will not compile if handed a reference to an error. ## RBAC Roles For Entra ID auth, assign one of these roles to the identity: | Role | Access | | ------------------------------- | -------------------------- | | `Storage Blob Data Reader` | Read-only | | `Storage Blob Data Contributor` | Read/write | | `Storage Blob Data Owner` | Full access including RBAC | ## Best Practices 1. **Use `cargo add` to manage dependencies, never edit `Cargo.toml` directly.** Add and remove Rust SDK dependencies with cargo commands instead of manual manifest edits. 2. **Add `azure_core` only when importing `azure_core` types directly.** If your code imports `azure_core::http::Url`, `azure_core::http::RequestContent`, or `azure_core::error::ErrorKind`, include `azure_core`; otherwise a direct dependency is optional. 3. **Use `DeveloperToolsCredential`** for local dev, **`ManagedIdentityCredential`** for production — Rust does not provide a single `DefaultAzureCredential` type 4. **Never hardcode credentials** — use environment variables or managed identity 5. **Use `RequestContent::from()`** to wrap data for blob uploads — ensures proper content handling by the SDK 6. **Assign RBAC roles** — ensure "Storage Blob Data Contributor" for write access 7. **Reuse clients** — clients are thread-safe; create once, share across tasks 8. **Prefer `BlobServiceClient` as the entry point** and derive container/blob clients from it ## Reference Links | Resource | Link | | ------------- | ------------------------------------------------------------------------------------ | | API Reference | https://docs.rs/crate/azure_storage_blob/latest | | crates.io | https://crates.io/crates/azure_storage_blob | | Source Code | https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob |