azure-storage-blob-rust

Azure Blob Storage Rust SDK

用于 Azure Blob Storage 的客户端库——Microsoft 面向云的对象存储解决方案。

以下示例需要使用经过审核且相互兼容的 crate 集，并替换所有资源占位符。请勿使用生产数据进行演示写入。

安装

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/

身份验证

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.clone()),
    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.
}

最佳实践

1. 使用 Entra ID 身份验证 — 开发时使用 DeveloperToolsCredential，生产环境使用 ManagedIdentityCredential
2. 检查覆盖行为 — 经过审核的上传 API 使用选项；if_not_exists 可防止意外替换
3. 使用 RequestContent::from() — 用于封装上传数据
4. 处理异步操作 — 使用 tokio 运行时
5. 检查 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 参考	https://docs.rs/azure_storage_blob
源代码	https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_blob
crates.io	https://crates.io/crates/azure_storage_blob

适用场景

当 Rust 应用需要上传/下载指定的 Azure Blob、读取其属性或管理获授权的容器时使用。

限制

• 示例是异步应用代码中的片段，依赖兼容且固定版本的 Azure crate，以及所需的 Tokio/Serde/Futures 依赖；使用前请核实所选版本的 API。示例已对照官方源代码/参考资料进行审核，但未在此处编译，也未针对云账户运行。
• 请使用具有最小权限的获授权租户、资源和身份。写入、覆盖、删除、检索备份及更改账户都需要相应范围；清理操作只能移除明确标识的临时资源。请限制请求、重试次数和下载字节数，并且不要记录负载、凭据或机密值。
• 请勿将输出视为环境特定验证、测试或专家审核的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请暂停并请求澄清。