使用 .NET 读取适用于 NoSQL 的 Azure Cosmos DB 中的项

项目
08/14/2024

适用范围： NoSQL

Azure Cosmos DB 中的项表示存储在容器中的特定实体。在 API for NoSQL 中，项由具有唯一标识符的 JSON 格式数据组成。

读取具有唯一标识符的项

适用于 NoSQL 的 Azure Cosmos DB 中的每个项都有 id 属性指定的唯一标识符。在容器范围内，两个项不能共享同一个唯一标识符。但是，Azure Cosmos DB 需要项的唯一标识符和分区键值来执行该项的快速点读取。如果只有唯一标识符可用，则必须执行效率较低的查询，以便跨多个逻辑分区查找项。若要了解有关点读取和查询的详细信息，请参阅优化读取数据的请求成本。

读取项

注意

本文中的示例假定你已定义一个 C# 类型来表示名为 Product 的数据：

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

若要执行项的点读取，请调用以下方法之一：

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

异步读取项

以下示例异步点读取单个项，并使用提供的泛型类型返回反序列化项：

// Read existing item from container
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Database.ReadItemAsync<> 方法读取项并返回一个类型为 ItemResponse<> 的对象。 ItemResponse<> 类型继承自 Response<> 类型，其中包含用于将对象转换为泛型类型的隐式转换运算符。若要了解有关隐式运算符的详细信息，请参阅用户定义的转换运算符。

或者，可以返回 ItemResponse<> 泛型类型并显式获取资源。更常规的 ItemResponse<> 类型还包含有关基础 API 操作的有用元数据。在此示例中，使用 RequestCharge 属性收集有关此操作的请求单位费用的元数据。

// Read existing item from container
ItemResponse<Product> readResponse = await container.ReadItemAsync<Product>(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get response metadata
double requestUnits = readResponse.RequestCharge;
HttpStatusCode statusCode = readResponse.StatusCode;

// Explicitly get item
Product readItemExplicit = readResponse.Resource;

将项作为流异步读取

此示例将项作为数据流直接读取：

// Read existing item from container
using ResponseMessage readItemStreamResponse = await container.ReadItemStreamAsync(
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

// Get stream from response
using StreamReader readItemStreamReader = new(readItemStreamResponse.Content);

// (optional) Get stream content
string content = await readItemStreamReader.ReadToEndAsync();

Container.ReadItemStreamAsync 方法将项作为 Stream 返回，而不反序列化内容。

如果不打算直接反序列化项，则使用流 API 可以通过将项作为流直接移交给应用程序的下一个组件来提高性能。有关如何针对高性能方案优化 SDK 的更多提示，请参阅 SDK 性能提示。

异步读取多个项

在此示例中，包含唯一标识符和分区键对的元组列表用于查找和检索多个项：

// Create partition key object
PartitionKey partitionKey = new("gear-surf-surfboards");

// Create list of tuples for each item
List<(string, PartitionKey)> itemsToFind = new()
{
    ("68719518388", partitionKey),
    ("68719518381", partitionKey)
};

// Read multiple items
FeedResponse<Product> feedResponse = await container.ReadManyItemsAsync<Product>(
    items: itemsToFind
);

foreach (Product item in feedResponse)
{
    Console.WriteLine($"Found item:\t{item.name}");
}

Container.ReadManyItemsAsync<> 根据提供的唯一标识符和分区键返回项列表。与使用 IN 语句提取大量独立项的查询相比，此操作在延迟方面的表现会更好。

后续步骤

现在你已读取各种项，请使用下一个指南查询项。

查询项

通过