azure-cosmos-rust

Azure Cosmos DB SDK for Rust

适用于 Azure Cosmos DB NoSQL API 的客户端库——全球分布式多模型数据库。

以下示例需要使用经过审查且彼此兼容的 crate，并替换所有资源占位符。演示写入时请勿使用生产数据。

安装

cargo add azure_data_cosmos@=0.37.1 azure_identity@=1.0.0 azure_core@=1.1.0

环境变量

export COSMOS_ENDPOINT="https://<account>.documents.azure.com:443/"
export COSMOS_DATABASE="mydb"
export COSMOS_CONTAINER="mycontainer"

身份验证

use azure_identity::DeveloperToolsCredential;
use azure_data_cosmos::{AccountEndpoint, AccountReference, CosmosClient, RoutingStrategy};

let credential = DeveloperToolsCredential::new(None)?;
let endpoint: AccountEndpoint = "https://<account>.documents.azure.com/".parse()?;
let account = AccountReference::with_credential(endpoint, credential.clone());
let client = CosmosClient::builder()
    .build(account, RoutingStrategy::ProximityTo("East US".into()))
    .await?;

客户端层级

客户端	用途	获取方式
CosmosClient	账户级操作	直接实例化
DatabaseClient	数据库操作	client.database_client()
ContainerClient	容器/项目操作	database.container_client()

核心工作流

获取数据库和容器客户端

let database = client.database_client("myDatabase");
let container = database.container_client("myContainer", None).await?;

创建项目

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Item {
    pub id: String,
    pub partition_key: String,
    pub value: String,
}

let item = Item {
    id: "1".into(),
    partition_key: "partition1".into(),
    value: "hello".into(),
};

container.create_item("partition1", "1", item, None).await?;

读取项目

let response = container.read_item("partition1", "1", None).await?;
let item: Item = response.into_model()?;

替换项目

let mut item: Item = container.read_item("partition1", "1", None).await?.into_model()?;
item.value = "updated".into();

container.replace_item("partition1", "1", item, None).await?;

修补项目

// Explicit preview opt-in: cargo add azure_data_cosmos@=0.37.1 --features preview_patch
use azure_data_cosmos::models::{PatchInstructions, PatchOperation};

let patch = PatchInstructions::from(vec![
    PatchOperation::set("/value", serde_json::json!("newValue")),
]);
let patched: Item = container.patch_item("partition1", "1", patch, None)
    .await?.into_model()?;

删除项目

container.delete_item("partition1", "1", None).await?;

经过审查的当前 API 使用异步 builder/容器初始化，并单独指定项目 ID。预览版 PATCH 并不保证可用于生产；请审查所选策略、冲突/重试行为和请求单位成本。官方 crate 参考。

密钥身份验证（可选）

使用功能标志启用基于密钥的身份验证：

cargo add azure_data_cosmos@=0.37.1 --features key_auth

最佳实践

1. 始终指定分区键——点读取和写入都需要分区键
2. 使用 into_model()?——将响应反序列化为你的类型
3. 为所有文档类型派生 Serialize 和 Deserialize
4. 使用 Entra ID 身份验证——优先使用 DeveloperToolsCredential，而非密钥身份验证
5. 重复使用客户端实例——客户端是线程安全且可重复使用的

经过审查的示例集使用 azure_data_cosmos 0.37.1 及兼容的 Azure core/credential crate。记录并提交 Cargo.lock；源码/API 审查不等同于编译器检查或实时服务测试。

参考链接

资源	链接
API 参考	https://docs.rs/azure_data_cosmos
源代码	https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos
crates.io	https://crates.io/crates/azure_data_cosmos

适用场景

当 Rust 应用需要 Cosmos DB NoSQL 项目 CRUD、分区键点读取、容器访问或明确选择启用的预览版修补功能时使用。

限制

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