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

  • 3 分

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

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

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

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

CosmosClient

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

CosmosClient client = new CosmosClient(endpoint, key);

データベースのサンプル

データベースの作成

CosmosClient.CreateDatabaseAsync メソッドは、同じ名前のデータベースが既に存在する場合、例外をスローします。

// New instance of Database class referencing the server-side database
Database database1 = await client.CreateDatabaseAsync(
    id: "adventureworks-1"
);

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

// New instance of Database class referencing the server-side database
Database database2 = await client.CreateDatabaseIfNotExistsAsync(
    id: "adventureworks-2"
);

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

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

// Reads a Database resource with the ID property of the Database resource you wish to read.
Database database = this.cosmosClient.GetDatabase(database_id);
DatabaseResponse response = 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
    });

その他のリソース