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

⚠️ Note: The azure_storage_blob crate is currently under active development and not all features may be implemented or work as intended. This crate is in beta and not suitable for Production environments. For any general feedback or usage issues, please open a GitHub issue here.

§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. 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_storage_blob::{BlobClient, BlobClientOptions};
use azure_identity::DefaultAzureCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a BlobClient that will authenticate through Microsoft Entra ID
    let credential = DefaultAzureCredential::new()?;
    let blob_client = BlobClient::new(
        "https://<storage_account_name>.blob.core.windows.net/", // endpoint
        "container_name".to_string(),                            // container name
        "blob_name".to_string(),                                 // blob name
        credential,                                              // credential
        Some(BlobClientOptions::default()),                      // BlobClient options
    )?;
    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

§Create `BlobClient`

use azure_storage_blob::{BlobClient, BlobClientOptions};
use azure_identity::DefaultAzureCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a BlobClient that will authenticate through Microsoft Entra ID
    let credential = DefaultAzureCredential::new()?;
    let blob_client = BlobClient::new(
        "https://<storage_account_name>.blob.core.windows.net/", // endpoint
        "container_name".to_string(),                            // container name
        "blob_name".to_string(),                                 // blob name
        credential,                                              // credential
        Some(BlobClientOptions::default()),                      // BlobClient options
    )?;
    Ok(())
}

§Upload Blob

use azure_core::http::RequestContent;
use azure_storage_blob::{BlobClient, BlobClientOptions};
use azure_identity::DefaultAzureCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let credential = DefaultAzureCredential::new()?;
    let blob_client = BlobClient::new(
        "https://<storage_account_name>.blob.core.windows.net/",
        "container_name".to_string(),
        "blob_name".to_string(),
        credential,
        Some(BlobClientOptions::default()),
    )?;

    let data = b"hello world";
    blob_client
        .upload(
            RequestContent::from(data.to_vec()), // data
            false,                               // overwrite
            u64::try_from(data.len())?,          // content length
            None,                                // upload options
        )
        .await?;
    Ok(())
}

§Get Blob Properties

use azure_storage_blob::{BlobClient, BlobClientOptions};
use azure_identity::DefaultAzureCredential;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {

    let credential = DefaultAzureCredential::new()?;
    let blob_client = BlobClient::new(
        "https://<storage_account_name>.blob.core.windows.net/",
        "container_name".to_string(),
        "blob_name".to_string(),
        credential,
        Some(BlobClientOptions::default()),
    )?;
    let blob_properties = blob_client.get_properties(
        None // get properties options
        )
        .await?;
    Ok(())
}

§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 crate::clients::BlobClient;
pub use crate::clients::BlobContainerClient;
pub use crate::clients::BlobServiceClient;

Modules§

clients
models

Structs§

BlobClientDeleteOptions: Options to be passed to BlobClient::delete()
BlobClientDownloadOptions: Options to be passed to BlobClient::download()
BlobClientGetPropertiesOptions: Options to be passed to BlobClient::get_properties()
BlobClientOptions: Options used when creating a BlobClient
BlobContainerClientCreateOptions: Options to be passed to BlobContainerClient::create()
BlobContainerClientDeleteOptions: Options to be passed to BlobContainerClient::delete()
BlobContainerClientGetPropertiesOptions: Options to be passed to BlobContainerClient::get_properties()
BlobContainerClientOptions: Options used when creating a BlobContainerClient
BlobServiceClientGetPropertiesOptions: Options to be passed to BlobServiceClient::get_properties()
BlobServiceClientOptions: Options used when creating a BlobServiceClient
BlockBlobClientCommitBlockListOptions: Options to be passed to BlockBlobClient::commit_block_list()
BlockBlobClientGetBlockListOptions: Options to be passed to BlockBlobClient::get_block_list()
BlockBlobClientStageBlockOptions: Options to be passed to BlockBlobClient::stage_block()
BlockBlobClientUploadOptions: Options to be passed to BlockBlobClient::upload()

Crate azure_storage_blobCopy item path