クイックスタート: MongoDB ドライバーを使う .NET 用 Azure Cosmos DB for MongoDB

[アーティクル]
03/28/2024

適用対象: MongoDB

MongoDB の使用を開始して、Azure Cosmos DB リソース内にデータベース、コレクション、ドキュメントを作成します。 Azure Developer CLI を使って最小限のソリューションを環境にデプロイするには、以下の手順に従います。

MongoDB 用 API リファレンスドキュメント | MongoDB パッケージ (NuGet)packages/Microsoft.Azure.Cosmos) | Azure Developer CLI

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
GitHub アカウント

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Developer CLI
Docker Desktop

設定

このプロジェクトの開発コンテナーをお使いの環境にデプロイします。次に、Azure Developer CLI (azd) を使って、Azure Cosmos DB for MongoDB アカウントを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

重要

GitHub アカウントには、ストレージとコア時間のエンタイトルメントが無料で含まれています。詳細については、GitHub アカウントに含まれるストレージとコア時間に関する記事を参照してください。

プロジェクトのルートディレクトリでターミナルを開きます。
azd auth login を使って Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使ってプロジェクトを初期化します。
```
azd init
```
初期化中に、一意の環境名を構成します。

ヒント

この環境名は、ターゲットリソースグループ名としても使用されます。このクイックスタートでは、msdocs-cosmos-db- の使用を検討してください。
azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
プロビジョニングプロセス中に、サブスクリプションと目的の場所を選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 5 分ほどかかる可能性があります。

Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。実行中のアプリの出力を確認します。

クライアントライブラリをインストールする

クライアントライブラリは、NuGet を介して Microsoft.Azure.Cosmos パッケージとして入手できます。

ターミナルを開き、/src/web フォルダーに移動します。
```
cd ./src/web
```
MongoDb.Driver パッケージがまだインストールされていない場合は、dotnet add package を使ってインストールします。
```
dotnet add package MongoDb.Driver
```
また、Azure.Identity パッケージがまだインストールされていない場合はインストールします。
```
dotnet add package Azure.Identity
```

オブジェクトモデル

アプリケーションのビルドを開始する前に、Azure Cosmos DB のリソースの階層について説明します。 Azure Cosmos DB には、リソースの作成とアクセスに使用される特定のオブジェクトモデルがあります。 Azure Cosmos DB によって、アカウント、データベース、コレクション、ドキュメントで構成される階層内にリソースが作成されます。

アカウント、データベース、コレクション、ドキュメントを含む Azure Cosmos DB 階層の図。

これらのリソースとやり取りするには、以下の MongoDB クラスを使用します。

MongoClient - このクラスは、Azure Cosmos DB での MongoDB 用 API レイヤーに対するクライアント側の論理表現を提供します。このクライアントオブジェクトは、サービスに対する要求の構成と実行に使用されます。
MongoDatabase - このクラスは、サービスに存在する (または、まだ存在しない) 場合があるデータベースへの参照です。データベースは、それに対するアクセスまたは操作の実行を試みると、サーバー側で検証されます。
Collection - このクラスは、まだサービスに存在しない可能性があるコレクションへの参照です。コレクションは、操作しようとすると、サーバー側で検証されます。

この記事で紹介しているサンプルコードでは、products という名前のコレクションを使用して adventureworks という名前のデータベースを作成します。 products コレクションは、名前、カテゴリ、数量、販売インジケーターなどの製品の詳細が含まれるように設計されています。各製品には、一意の識別子も含まれています。

クライアントを認証する

プロジェクトディレクトリから、 Program.cs ファイルを開きます。エディターで、MongoDB.Driver の using ディレクティブを追加します。

using MongoDB.Driver;

コンストラクターを使って MongoClient クラスの新しいインスタンスを定義し、Environment.GetEnvironmentVariable で前に設定した接続文字列を読み込みます。

// New instance of CosmosClient class
var client = new MongoClient(Environment.GetEnvironmentVariable("MONGO_CONNECTION"));

データベースを作成する

MongoClient.GetDatabase メソッドを使用して、新しいデータベースを作成します (まだ存在しない場合)。このメソッドは、既存または新しく作成されたデータベースへの参照を返します。

// Database reference with creation if it does not already exist
var db = client.GetDatabase("adventure");

コレクションの作成

MongoDatabase.GetCollection は、新しいコレクションがまだ存在しない場合は、新しいコレクションを作成し、そのコレクションへの参照を返します。

// Container reference with creation if it does not alredy exist
var _products = db.GetCollection<Product>("products");

項目を作成する

コレクションに新しい項目を作成する最も簡単な方法は、JSON にシリアル化するすべてのメンバーを含む C# クラス、またはレコード型を作成することです。この例では、C# レコードには一意の識別子、パーティションキーの カテゴリ フィールド、および追加 の名前、数量、および販売フィールドがあります。

public record Product(
    string Id,
    string Category,
    string Name,
    int Quantity,
    bool Sale
);

IMongoCollection<TDocument>.InsertOne を呼び出し、Product レコードを使用してコレクション内に項目を作成します。

// Create new object and upsert (create or replace) to container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Yamba Surfboard", 
    12, 
    false
));

アイテムを取得する

Azure Cosmos DB では、Linq を使用してクエリを作成することで項目を取得できます。 SDK で、IMongoCollection.FindAsync<> を呼び出し、C# の式を渡して結果をフィルター処理します。

// Read a single item from container
var product = (await _products.FindAsync(p => p.Name.Contains("Yamba"))).FirstOrDefault();
Console.WriteLine("Single product:");
Console.WriteLine(product.Name);

クエリ項目

項目を挿入した後、コレクションを IQueryable として処理して、特定のフィルターに一致するすべての項目を取得するクエリを実行できます。この例では、式を使用してカテゴリ別に製品をフィルター処理します。 AsQueryable が呼び出されたら、MongoQueryable.Where を呼び出して、フィルター処理された一連の項目を取得します。

// Read multiple items from container
_products.InsertOne(new Product(
    Guid.NewGuid().ToString(),
    "gear-surf-surfboards",
    "Sand Surfboard",
    4,
    false
));

var products = _products.AsQueryable().Where(p => p.Category == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var prod in products)
{
    Console.WriteLine(prod.Name);
}

コードの実行

このアプリは、Azure Cosmos DB MongoDB API データベースとコレクションを作成します。次に、この例では項目を作成し、まったく同じ項目を読み取ります。最後に、2 番目の項目を作成し、複数の項目を返すクエリを実行します。この例では、各ステップで、実行したステップに関するメタデータをコンソールに出力します。

アプリを実行するには、ターミナルを使用してアプリケーションディレクトリに移動し、アプリケーションを実行します。

dotnet run

アプリの出力は次の例のようになります。

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

リソースをクリーンアップする

Azure Cosmos DB for MongoDB アカウントが不要になった場合、対応するリソースグループは削除してかまいません。

az group delete コマンドを使用して、リソースグループを削除します。

az group delete --name $resourceGroupName

Remove-AzResourceGroup コマンドレットを使用して、リソースグループを削除します。

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Azure portal で先ほど作成したリソースグループに移動します。

ヒント

このクイックスタートでは、msdocs-cosmos-quickstart-rg という名前にするようにお勧めしました。
[リソースグループの削除] を選択します。
[削除しますか] のダイアログで、リソースグループの名前を入力し、[削除] を選択します。