快速入门：将 Azure Cosmos DB for NoSQL 与 Azure SDK for Rust 配合使用

项目
2025-04-10
适用于: ✅ NoSQL

在本快速入门中，你将使用 Azure SDK for Rust 部署基本的 Azure Cosmos DB for NoSQL 应用程序。 Azure Cosmos DB for NoSQL 是一种无架构数据存储，允许应用程序在云中存储非结构化数据。使用 Azure SDK for Rust 查询容器中的数据，并针对单个项执行常见作。

重要

Rust SDK for Azure Cosmos DB 当前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能不受支持，或其支持能力受限。

有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

API 参考文档 | 库源代码 | Crate (Rust) | Azure 开发人员 CLI

先决条件

Docker Desktop
Rust 1.80 或更高版本

如果没有 Azure 帐户，请在开始前创建一个免费帐户。

安装客户端库

客户端库可以通过 Rust 获取，作为 azure_data_cosmos Crate。

如果尚未安装，请使用 cargo install 安装 azure_data_cosmos Crate。
```
cargo install azure_data_cosmos
```
此外，如果尚未安装 azure_identity Crate，请进行安装。
```
cargo install azure_identity
```

导入库文件

将 DefaultAzureCredential、CosmosClient、PartitionKey 和 Query 类型导入到你的应用程序代码。

use azure_data_cosmos::{CosmosClient, PartitionKey, Query};
use azure_identity::DefaultAzureCredential;

对象模型

名称	描述
`CosmosClient`	此类型是主要客户端，用于管理帐户范围的元数据或数据库。
`DatabaseClient`	此类型表示帐户内的数据库。
`ContainerClient`	此类型主要用于对容器或容器中存储的项执行读取、更新和删除操作。

模板中的示例代码使用名为 cosmicworks 的数据库和名为 products 的容器。 products 容器包含每个产品的名称、类别、数量、唯一标识符和销售标志等详细信息。该容器使用 /category 属性作为逻辑分区键。

验证客户端

此示例使用 CosmosClient 创建一个新的 CosmosClient::new 实例并使用 DefaultAzureCredential 实例进行身份验证。

let credential = DefaultAzureCredential::new()?;

let client = CosmosClient::new(&endpoint, credential, None)?;

获取数据库

使用 client.database 检索名为 cosmicworks 的现有数据库。

let database = client.database_client("cosmicworks");

获取容器

使用 products 检索现有的 database.container 容器。

let container = database.container_client("products");

创建项

使用要序列化为 JSON 的所有成员构建一个新类型。在此示例中，该类型具有唯一标识符以及用于类别、名称、数量、价格和销售的字段。在此类型上派生 serde::Serialize 特征，以便它可序列化为 JSON。

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
pub struct Item {
    pub id: String,
    pub category: String,
    pub name: String,
    pub quantity: i32,
    pub price: f64,
    pub clearance: bool,
}

使用 container.upsert_item 在容器中创建某个项。如果该项已经存在，此方法会“更新插入”该项，从而有效地替换该项。

let item = Item {
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb".to_string(),
    category: "gear-surf-surfboards".to_string(),
    name: "Yamba Surfboard".to_string(),
    quantity: 12,
    price: 850.00,
    clearance: false,
};

let partition_key = PartitionKey::from(item.category.clone());
        
let partition_key = PartitionKey::from(item.category.clone());

container.upsert_item(partition_key, item.clone(), None).await?;

读取项

同时使用唯一标识符 (id) 和分区键字段来执行点读取操作。使用 container.ReadItem 以有效检索特定项。

let item_id = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb";
let item_partition_key = "gear-surf-surfboards";

let response = container.read_item(item_partition_key, item_id, None).await?;

let item: Item = response.into_json_body().await?;

查询项

使用 container.NewQueryItemsPager 对容器中的多个项执行查询。使用此参数化查询查找指定类别中的所有项：

SELECT * FROM products p WHERE p.category = @category

let item_partition_key = "gear-surf-surfboards";

let query = Query::from("SELECT * FROM c WHERE c.category = @category")
    .with_parameter("@category", item_partition_key)?;

let mut pager = container.query_items::<Item>(query, item_partition_key, None)?;

while let Some(page_response) = pager.next().await {

    let page = page_response?.into_body().await?;

    for item in page.items {
        // Do something
    }

}

探索您的数据

使用适用于 Azure Cosmos DB 的 Visual Studio Code 扩展来浏览 NoSQL 数据。可以执行核心数据库操作，这些操作包括但不限于：

使用剪贴簿或查询编辑器执行查询
修改、更新、创建和删除项
从其他源导入批量数据
管理数据库和容器

有关详细信息，请参阅如何使用 Visual Studio Code 扩展来浏览 Azure Cosmos DB for NoSQL 数据。

下一步

用于 Azure Cosmos DB for NoSQL 的 Azure SDK for Rust 示例

通过