azure-storage-blob-rust

用途

azure_storage_blob 是 Azure Blob Storage 的 Rust 客户端库，面向 Microsoft 云对象存储。适用于 Rust 应用上传或下载指定的 Azure Blob、读取其属性，或管理已授权的容器。

安装

cargo add azure_storage_blob@=1.1.0 azure_identity@=1.0.0 azure_core@=1.1.0

环境变量

export AZURE_STORAGE_ACCOUNT_NAME="<storage-account-name>"
# Endpoint: https://<account>.blob.core.windows.net/

认证

示例使用 Entra ID 认证，通过 DeveloperToolsCredential 创建凭据，并构造 BlobClient：

use azure_identity::DeveloperToolsCredential;
use azure_core::http::Url;
use azure_storage_blob::clients::{BlobClient, BlobClientOptions};

let credential = DeveloperToolsCredential::new(None)?;
let blob_client = BlobClient::new(
    Url::parse("https://<account>.blob.core.windows.net/container-name/blob-name")?,
    Some(credential),
    Some(BlobClientOptions::default()),
)?;

客户端类型

BlobServiceClient：账户级操作，列举容器。
BlobContainerClient：容器操作，列举 Blob。
BlobClient：单个 Blob 的操作。

核心操作

上传 Blob

use azure_core::http::RequestContent;
use azure_storage_blob::models::BlobClientUploadOptions;

let data = b"hello world";
blob_client
    .upload(
        RequestContent::from(data.to_vec()),
        Some(BlobClientUploadOptions::if_not_exists()), // fail rather than overwrite an existing blob
    )
    .await?;

下载 Blob

let response = blob_client.download(None).await?;
// Check the approved size before fetching; use download_into with a bounded buffer for large data.
let content = response.body.collect().await?;
// Process authorized bytes; do not log the payload.

获取 Blob 属性

let properties = blob_client.get_properties(None).await?;
// Read the version-specific response header trait; properties is a response, not a content_length field.
// Do not infer a body/size limit from successful metadata access alone.

删除 Blob

blob_client.delete(None).await?;

容器操作

use azure_storage_blob::clients::BlobContainerClient;
use futures::TryStreamExt;

let container_client = BlobContainerClient::new(
    Url::parse("https://<account>.blob.core.windows.net/container-name")?,
    Some(credential),
    None,
)?;

// Create container
container_client.create(None).await?;

// List blobs
let mut pager = container_client.list_blobs(None)?;
while let Some(page) = pager.try_next().await? {
    let listing = page.into_model()?;
    // Process this listing page; apply an explicit maximum-page budget.
}

最佳实践

使用 Entra ID 认证：开发用 DeveloperToolsCredential，生产用 ManagedIdentityCredential。
注意覆盖行为：上传 API 通过选项控制，if_not_exists 可防止意外替换。
使用 RequestContent::from() 包装上传数据。
处理异步操作：使用 tokio 运行时。
检查 RBAC 权限：确保具备“Storage Blob Data Contributor”角色。

RBAC 权限

使用 Entra ID 认证时，可分配以下角色之一：

Storage Blob Data Reader：只读。
Storage Blob Data Contributor：读写。
Storage Blob Data Owner：Blob 数据访问及受支持的所有权/ACL 管理；不授予一般 Azure RBAC 角色分配权限。

版本说明

示例 API 对应 BlobClient 1.1.0；更早版本使用不同的构造函数/上传签名。应使用项目兼容的 Azure crate 版本，避免混用。示例集使用 azure_storage_blob 1.1.0 及兼容的 Azure core/credential crate，建议记录并提交 Cargo.lock；源码/API 审查不等于编译器或实时服务测试。

参考链接

API Reference：https://docs.rs/azure_storage_blob
Source Code：https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob
crates.io：https://crates.io/crates/azure_storage_blob

限制

示例是异步应用代码中的片段，需搭配兼容且固定版本的 Azure crate 以及所需的 Tokio/Serde/Futures 依赖；使用前请核对所选版本的 API。示例仅对照官方源码/参考进行审查，未在此处编译或针对云账户运行。

请使用已授权的租户、资源和最小权限身份。写入、覆盖、删除、备份检索和账户变更需要相应范围；清理只能移除明确标识的一次性资源。应限制请求、重试和下载字节数，不要记录负载、凭据或机密值。

不要将输出视为环境特定验证、测试或专家审查的替代。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。