Azure Cosmos DB Rust SDK

azure-cosmos-rust
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.30/5
使用16.2K

Azure Cosmos DB Rust SDK

Azure Cosmos DB NoSQL API 的客户端库 —— 一款全球分布、多模型的数据库。

安装

sh
cargo add azure_data_cosmos azure_identity

环境变量

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

身份验证

rust
use azure_identity::DeveloperToolsCredential;
use azure_data_cosmos::CosmosClient;

let credential = DeveloperToolsCredential::new(None)?;
let client = CosmosClient::new(
    "https://<account>.documents.azure.com:443/",
    credential.clone(),
    None,
)?;

客户端层级

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

核心工作流

获取数据库和容器客户端

rust
let database = client.database_client("myDatabase");
let container = database.container_client("myContainer");

创建项目

rust
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", item, None).await?;

读取项目

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

替换项目

rust
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?;

补丁更新项目 (Patch)

rust
use azure_data_cosmos::models::PatchDocument;

let patch = PatchDocument::default()
    .with_add("/newField", "newValue")?
    .with_remove("/oldField")?;


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

删除项目

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

密钥认证 (可选)

通过 feature flag 启用基于密钥的身份验证：

sh
cargo add azure_data_cosmos --features key_auth

最佳实践

1. 始终指定分区键 —— 点读和写入操作必须提供。
2. 使用 into_model()? —— 将响应反序列化为自定义类型。
3. 派生 Serialize 和 Deserialize —— 为所有文档类型实现这两个 trait。
4. 优先使用 Entra ID 认证 —— 推荐使用 DeveloperToolsCredential 而非密钥认证。
5. 复用客户端实例 —— 客户端是线程安全的且可复用。

参考链接

| 资源 | 链接 |
|----------|------|
| 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 |

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如有不明确之处，请停止并寻求澄清。
如果缺少必要的输入、权限、安全边界或成功标准，请进行确认。