Azure Cosmos DB 用 Microsoft .NET SDK v3 を探索する

  • 3 分

このユニットでは、API for NoSQL 用の Azure Cosmos DB .NET SDK v3 に焦点を当てます。 (Microsoft.Azure.Cosmos NuGet パッケージ。) 以前のバージョンの .NET SDK に馴染みがある場合、コレクションやドキュメントという用語に親しんでいるかもしれません。

azure-cosmos-dotnet-v3 GitHub リポジトリには、最新の .NET サンプル ソリューションがあります。 これらのソリューションを使用して、Azure Cosmos DB リソースに対する CRUD (作成、読み取り、更新、および削除) などの一般的な操作を実行します。

Azure Cosmos DB では複数の API モデルがサポートされているため、.NET SDK のバージョン 3 では、"コンテナー" や "項目" といった一般的な用語が使用されます。 コンテナーは、コレクション、グラフ、テーブルになる場合があります。 項目は、ドキュメント、エッジ/頂点、行になる場合があり、コンテナー内のコンテンツです。

理解する必要のある、主要な一部の操作を示す例を以下に示します。 その他の例については、前述の GitHub リンクにアクセスしてください。 次のすべての例では、メソッドの非同期バージョンを使用しています。

CosmosClient

接続文字列を使用して、新しい CosmosClient を作成します。 CosmosClient はスレッドセーフです。 アプリケーションの有効期間ごとに CosmosClient の 1 つのインスタンスを維持することをお勧めします。これにより、効率的な接続管理とパフォーマンスが実現します。

CosmosClient client = new CosmosClient(endpoint, key);

データベースのサンプル

データベースを作成する

CosmosClient.CreateDatabaseIfNotExistsAsync により、データベースが存在するかどうかが確認され、存在しない場合は作成されます。 既存のデータベースがあるかどうかを確認するには、データベースの id のみが使用されます。

// An object containing relevant information about the response
DatabaseResponse databaseResponse = await client.CreateDatabaseIfNotExistsAsync(databaseId, 10000);

ID によってデータベースを読み取る

非同期操作として Azure Cosmos DB サービスからデータベースを読み取ります。

DatabaseResponse readResponse = await database.ReadAsync();

データベースの削除

非同期操作としてデータベースを削除します。

await database.DeleteAsync();

コンテナーの例

コンテナーを作成する

Database.CreateContainerIfNotExistsAsync メソッドにより、コンテナーが存在するかどうかが確認され、存在しない場合は作成されます。 既存のコンテナーがあるかどうかを確認するのに使用されるのは、コンテナー id のみです。

// Set throughput to the minimum value of 400 RU/s
ContainerResponse simpleContainer = await database.CreateContainerIfNotExistsAsync(
    id: containerId,
    partitionKeyPath: partitionKey,
    throughput: 400);

ID によるコンテナーの取得

Container container = database.GetContainer(containerId);
ContainerProperties containerProperties = await container.ReadContainerAsync();

コンテナーを削除する

非同期操作としてコンテナーを削除します。

await database.GetContainer(containerId).DeleteContainerAsync();

項目の例

項目を作成する

Container.CreateItemAsync メソッドを使用して、項目を作成します。 メソッドには、id プロパティと partitionKey を含んでいる必要がある JSON シリアル化可能なオブジェクトが必要です。

ItemResponse<SalesOrder> response = await container.CreateItemAsync(salesOrder, new PartitionKey(salesOrder.AccountNumber));

項目を読み取る

Container.ReadItemAsync メソッドを使用して、項目を読み取ります。 メソッドには、項目をシリアル化するための種類と、id プロパティと partitionKey が必要です。

string id = "[id]";
string accountNumber = "[partition-key]";
ItemResponse<SalesOrder> response = await container.ReadItemAsync(id, new PartitionKey(accountNumber));

項目にクエリを実行する

Container.GetItemQueryIterator メソッドを使うと、SQL ステートメントをパラメーター化された値と共に使用して Azure Cosmos データベース内のコンテナー下の項目用にクエリを作成できます。 FeedIterator が返されます。

QueryDefinition query = new QueryDefinition(
    "select * from sales s where s.AccountNumber = @AccountInput ")
    .WithParameter("@AccountInput", "Account1");

FeedIterator<SalesOrder> resultSet = container.GetItemQueryIterator<SalesOrder>(
    query,
    requestOptions: new QueryRequestOptions()
    {
        PartitionKey = new PartitionKey("Account1"),
        MaxItemCount = 1
    });

その他のリソース