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

适用范围: 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
);

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

异步读取项

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

// 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 语句提取大量独立项的查询相比,此操作在延迟方面的表现会更好。

后续步骤

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