.NET を使用して Azure Cosmos DB for NoSQL の項目を読み取る

[アーティクル]
08/15/2024

適用対象: NoSQL

Azure Cosmos DB 内の項目は、コンテナー内に格納されている特定のエンティティを表します。 NoSQL 用 API では、項目は一意の識別子を含む JSON 形式のデータから成ります。

一意識別子を使用した項目の読み取り

Azure Cosmos DB for NoSQL 内のすべての項目には、id プロパティで指定された一意識別子があります。 1 つのコンテナーのスコープ内で 2 つの項目が同じ一意識別子を共有することはできません。ただし、Azure Cosmos DB では、その項目の迅速な "ポイント読み取り" を実行するために、項目の一意識別子とパーティションキー値の両方が必要です。一意識別子のみが使用できる場合は、効率が劣るクエリを実行して、複数の論理パーティションにわたって項目を検索する必要があります。ポイント読み取りとクエリの詳細については、データの読み取りに対する要求コストの最適化に関する記事を参照してください。

項目を読み取る

注意

この記事の例は、Product という名前のデータを表すために C# 型が既に定義されていることを前提としています。

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

項目のポイント読み取りを実行するには、次のいずれかのメソッドを呼び出します。

ReadItemAsync<>
ReadItemStreamAsync<>
ReadManyItemsAsync<>

項目を非同期的に読み取る

次の例は、1 つの項目のポイント読み取りを非同期的に行い、指定されたジェネリック型を使用して逆シリアル化された項目を返します。

// 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 ステートメントを使うクエリよりも待機時間について優れたパフォーマンスを発揮することを目的としています。

次のステップ

さまざまな項目を読み取りを行ったので、次のガイドを使用して項目のクエリを実行します。

クエリ項目

次の方法で共有