Azure Cosmos DB for NoSQL SDK を使用して変更フィード イベントを処理する

Azure Cosmos DB for NoSQL の変更フィードは、プラットフォームからのイベントによって駆動される補足アプリケーションを作成するためのカギとなります。 Azure Cosmos DB for NoSQL 用の .NET SDK には、変更フィードと統合し、コンテナー内の操作に関する通知をリッスンするアプリケーションを構築するためのクラス一式が用意されています。

このラボでは、.NET SDK の変更フィード プロセッサ機能を使用して、指定したコンテナー内の項目で作成または更新操作が実行されたという通知を受け取るアプリケーションを作成します。

開発環境を準備する

このラボで作業している環境に DP-420 のラボ コードのリポジトリをまだクローンしていない場合は、次の手順に従ってクローンします。 それ以外の場合は、以前にクローンしたフォルダーを Visual Studio Code で開きます。

  1. Visual Studio Code を起動します。

    📝 Visual Studio Code インターフェイスについてまだよく理解していない場合は、Visual Studio Code の入門ガイドを参照してください

  2. コマンド パレットを開き、Git: Clone を実行して、任意のローカル フォルダーに https://github.com/microsoftlearning/dp-420-cosmos-db-dev GitHub リポジトリをクローンします。

    💡 Ctrl + Shift + P キーボード ショートカットを使用してコマンド パレットを開くことができます。

  3. リポジトリが複製されたら、Visual Studio Code で選択したローカル フォルダーを開きます。

Azure Cosmos DB for NoSQL アカウントを作成する

Azure Cosmos DB は、複数の API をサポートするクラウドベースの NoSQL データベース サービスです。 Azure Cosmos DB アカウントを初めてプロビジョニングするときに、そのアカウントでサポートする API (たとえば、Mongo API や NoSQL API) を選択します。 Azure Cosmos DB for NoSQL アカウントのプロビジョニングが完了したら、エンドポイントとキーを取得し、Azure SDK for .NET または任意の他の SDK を使用して Azure Cosmos DB for NoSQL アカウントに接続する際に使用できます。

  1. 新しい Web ブラウザー ウィンドウまたはタブで、Azure portal (portal.azure.com) に移動します。

  2. ご利用のサブスクリプションに関連付けられている Microsoft 資格情報を使用して、ポータルにサインインします。

  3. [+ リソースの作成] を選択し、Cosmos DB を検索して、新しい Azure Cosmos DB for NoSQL アカウント リソースを作成します。以下を設定して、残りの設定はすべて既定値のままにします。

    設定 Value
    サブスクリプション ’‘既存の Azure サブスクリプション’’
    リソース グループ ’‘既存のリソース グループを選択するか、新しいものを作成します’’
    アカウント名 ’‘グローバルに一意の名前を入力します’’
    場所 ’‘使用可能なリージョンを選びます’’
    容量モード サーバーレス

    📝 ご利用のラボ環境には、新しいリソース グループを作成できない制限が存在する場合があります。 その場合は、事前に作成されている既存のリソース グループを使用します。

  4. デプロイ タスクが完了するまで待ってから、このタスクを続行してください。

  5. 新しく作成された Azure Cosmos DB アカウント リソースに移動し、 [キー] ペインに移動します。

  6. このペインには、SDK からアカウントに接続するために必要な接続の詳細と資格情報が含まれています。 具体的な内容は次のとおりです。

    1. [URI] フィールドに注目します。 このエンドポイントの値は、この演習で後ほど使用します。

    2. [主キー] フィールドに注目してください。 このキーの値は、この演習で後ほど使用します。

  7. リソース メニューで [データ エクスプローラー] を選択します。

  8. [データ エクスプローラー] ペインで、[新しいコンテナー] を展開してから、[新しいデータベース] を選択します。

  9. [新しいデータベース] ポップアップで、各設定に次の値を入力してから [OK] を選択します。

    設定 Value
    データベース ID cosmicworks

  10. [データ エクスプローラー] ペインに戻り、階層内の cosmicworks データベース ノードを確認します。

  11. [データ エクスプローラー] ペインで、 [新しいコンテナー] を選択します。

  12. [新しいコンテナー] ポップアップで、各設定に次の値を入力してから [OK] を選択します。

    設定 Value
    データベース ID ’‘既存の | cosmicworks を使用します’’
    コンテナー ID products
    パーティション キー /categoryId

  13. [データ エクスプローラー] ペインに戻り、cosmicworks データベース ノードを展開して、階層内の products コンテナー ノードを確認します。

  14. [データ エクスプローラー] ペインで、[新しいコンテナー] を再度選択します。

  15. [新しいコンテナー] ポップアップで、各設定に次の値を入力してから [OK] を選択します。

    設定 Value
    データベース ID ’‘既存の | cosmicworks を使用します’’
    コンテナー ID productslease
    パーティション キー /partitionKey

  16. [データ エクスプローラー] ペインに戻り、cosmicworks データベース ノードを展開し、階層内の productslease コンテナー ノードを確認します。

  17. Visual Studio Code に戻ります。

.NET SDK で変更フィード プロセッサを実装する

Microsoft.Azure.Cosmos.Container クラスには、変更フィード プロセッサをフルーエントにビルドするための一連のメソッドが用意されています。 開始するには、監視対象のコンテナーへの参照、リース コンテナー、C# のデリゲート (変更の各バッチを処理するため) が必要です。

  1. [エクスプローラー] ウィンドウで、13-change-feed フォルダーを参照します。

  2. product.cs コード ファイルを開きます。

  3. Product クラスとその対応するプロパティを確認します。 具体的には、このラボでは id および name プロパティを使用します。

  4. Visual Studio Code の [エクスプローラー] ペインに戻り、script.cs コード ファイルを開きます。

  5. endpoint という名前の既存の変数を、先ほど作成した Azure Cosmos DB アカウントの endpoint に設定された値で更新します。

     string endpoint = "<cosmos-endpoint>";

    📝 たとえば、ご自分のエンドポイントが https­://dp420.documents.azure.com:443/ の場合、C# ステートメントは string endpoint = “https­://dp420.documents.azure.com:443/”; になります。

  6. key という名前の既存の変数を、先ほど作成した Azure Cosmos DB アカウントの key に設定された値で更新します。

     string key = "<cosmos-key>";

    📝 たとえば、キーが fDR2ci9QgkdkvERTQ== の場合、C# ステートメントは string key = “fDR2ci9QgkdkvERTQ==”; になります。

  7. client 変数の GetContainer メソッドを使用して、データベースの名前 (cosmicworks) とコンテナーの名前 (products) を使用して既存のコンテナーを取得し、結果を Container 型の sourceContainer という名前の変数に格納します。

     Container sourceContainer = client.GetContainer("cosmicworks", "products");

  8. client 変数の GetContainer メソッドを使用して、データベースの名前 (cosmicworks) とコンテナーの名前 (productslease) を使用して既存のコンテナーを取得し、結果を Container 型の leaseContainer という名前の変数に格納します。

     Container leaseContainer = client.GetContainer("cosmicworks", "productslease");

  9. 2 つの入力パラメーターを持つ空の非同期匿名関数を使用して、ChangesHandler<> 型の handleChanges という名前の新しいデリゲート変数を作成します。

    1. IReadOnlyCollection<Product> 型の changes という名前のパラメーター。

    2. CancellationToken 型の cancellationToken という名前のパラメーター。

     ChangesHandler<Product> handleChanges = async (
     IReadOnlyCollection<Product> changes,
     CancellationToken cancellationToken
 ) => {
 };

  10. 匿名関数内で、組み込みの Console.WriteLine 静的メソッドを使用して、生文字列 START\tHandling batch of changes… を出力します。

     Console.WriteLine($"START\tHandling batch of changes...");

  11. 引き続き、匿名関数内で、変数 product を使用して changes 変数を反復処理する foreach ループを作成して、Product 型のインスタンスを表します。

     foreach(Product product in changes)
 {
 }

  12. 匿名関数の foreach ループ内で、組み込みの非同期 Console.WriteLineAsync 静的メソッドを使用して、product 変数の id および name プロパティを出力します。

     await Console.Out.WriteLineAsync($"Detected Operation:\t[{product.id}]\t{product.name}");

  13. foreach ループおよび匿名関数の外部で、次のパラメーターを使用して sourceContainer 変数で GetChangeFeedProcessorBuilder<> を呼び出した結果を格納する builder という名前の新しい変数を作成します。

    パラメーター Value
    processorName productsProcessor
    onChangesDelegate handleChanges 
     var builder = sourceContainer.GetChangeFeedProcessorBuilder<Product>(
     processorName: "productsProcessor",
     onChangesDelegate: handleChanges
 );

  14. WithInstanceName メソッドを consoleApp のパラメーターを指定して呼び出し、WithLeaseContainer メソッドを leaseContainer のパラメーターを指定して呼び出し、Build メソッドを builder 変数でフルーエントに呼び出し、結果を ChangeFeedProcessor 型の processor という名前の変数に格納します。

     ChangeFeedProcessor processor = builder
     .WithInstanceName("consoleApp")
     .WithLeaseContainer(leaseContainer)
     .Build();

  15. processor 変数の StartAsync を非同期に呼び出します。

     await processor.StartAsync();

  16. 組み込みの Console.WriteLine および Console.ReadKey 静的メソッドを使用して、コンソールに出力し、アプリケーションにキーの押下を待機させます。

     Console.WriteLine($"RUN\tListening for changes...");
 Console.WriteLine("Press any key to stop");
 Console.ReadKey();

  17. processor 変数の StopAsync を非同期に呼び出します。

     await processor.StopAsync();

  18. 完了すると、コード ファイルが次のようになるはずです。

     using Microsoft.Azure.Cosmos;
 using static Microsoft.Azure.Cosmos.Container;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Container sourceContainer = client.GetContainer("cosmicworks", "products");
 Container leaseContainer = client.GetContainer("cosmicworks", "productslease");
    
 ChangesHandler<Product> handleChanges = async (
     IReadOnlyCollection<Product> changes,
     CancellationToken cancellationToken
 ) => {
     Console.WriteLine($"START\tHandling batch of changes...");
     foreach(Product product in changes)
     {
         await Console.Out.WriteLineAsync($"Detected Operation:\t[{product.id}]\t{product.name}");
     }
 };
    
 var builder = sourceContainer.GetChangeFeedProcessorBuilder<Product>(
         processorName: "productsProcessor",
         onChangesDelegate: handleChanges
     );
    
 ChangeFeedProcessor processor = builder
     .WithInstanceName("consoleApp")
     .WithLeaseContainer(leaseContainer)
     .Build();
    
 await processor.StartAsync();
    
 Console.WriteLine($"RUN\tListening for changes...");
 Console.WriteLine("Press any key to stop");
 Console.ReadKey();
    
 await processor.StopAsync();

  19. script.cs ファイルを保存します。

  20. Visual Studio Code で、13-change-feed フォルダーのコンテキスト メニューを開き、[統合ターミナルで開く] を選択して新しいターミナル インスタンスを開きます。

  21. dotnet run コマンドを使用して、プロジェクトをビルドして実行します。

     dotnet run

  22. Visual Studio Code とターミナルの両方を開いたままにします。

    📝 別のツールを使用して、Azure Cosmos DB for NoSQL コンテナーに項目を生成します。 項目を生成したら、このターミナルに戻って出力を確認します。 ターミナルを早々に閉じないようにします。

Azure Cosmos DB for NoSQL アカウントにサンプル データをシードする

cosmicworks データベースと products コンテナーを作成するコマンドライン ユーティリティを使用します。 ツールで一連の項目を作成して、ターミナル ウィンドウで実行されている変更フィード プロセッサを使用して確認します。

  1. Visual Studio Codeで、[ターミナル] メニューを開き、[ターミナルの分割] を選択して、新しいターミナルを既存のインスタンスと並べて開きます。

  2. コンピューターでグローバルに使用するために cosmicworks コマンドライン ツールをインストールします。

     dotnet tool install cosmicworks --global --version 1.*

    💡 このコマンドが完了するまで数分かかる場合があります。 過去にこのツールの最新バージョンを既にインストールしている場合は、このコマンドによって警告メッセージ (*ツール ‘cosmicworks’ は既にインストールされています) が出力されます。

  3. cosmicworks を実行し、次のコマンドライン オプションを使用して Azure Cosmos DB アカウントをシードします。

    オプション Value
    –endpoint ’‘このラボで先ほどコピーしたエンドポイントの値’’
    –key ’‘このラボで先ほどコピーしたキーの値’’
    –datasets product 
     cosmicworks --endpoint <cosmos-endpoint> --key <cosmos-key> --datasets product

    📝 たとえば、エンドポイントが https­://dp420.documents.azure.com:443/ で、キーが fDR2ci9QgkdkvERTQ== の場合、コマンドは次のようになります。cosmicworks --endpoint https://dp420.documents.azure.com:443/ --key fDR2ci9QgkdkvERTQ== --datasets product

  4. cosmicworks コマンドによって、データベース、コンテナー、および項目がアカウントに設定されるまで待ちます。

  5. .NET アプリケーションのターミナル出力を確認します。 ターミナルには、変更フィードを使用して送信された変更ごとに、[検出された操作] というメッセージが出力されます。

  6. 両方の統合ターミナルを閉じます。

  7. Visual Studio Code を閉じます。