ポータルと Azure Cosmos DB for NoSQL SDK で整合性モデルを構成する

新しい Azure Cosmos DB for NoSQL アカウントの既定の整合性レベルは、セッションの整合性です。 この既定の設定は、今後のすべての要求に対して変更できます。 個々の要求レベルでは、さらに一歩進んで、その特定の要求の整合性レベルを緩和できます。

このラボでは、Azure Cosmos DB for NoSQL アカウントの既定の整合性レベルを構成してから、SDK を使用して個々の操作の整合性レベルを構成します。

開発環境を準備する

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

  1. 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 サブスクリプション’’
    リソース グループ ’‘既存のリソース グループを選択するか、新しいものを作成します’’
    アカウント名 ’‘グローバルに一意の名前を入力します’’
    場所 ’‘使用可能なリージョンを選びます’’
    容量モード プロビジョニング済みスループット
    グローバル配布 | Geo 冗長性 有効にする
    Apply Free Tier Discount (Free レベル割引の適用) 適用しない

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

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

  5. 新しく作成した Azure Cosmos DB アカウント リソースにアクセスし、[データをグローバルにレプリケートする] ペインに移動します。

  6. [データをグローバルにレプリケートする] ペインで、アカウントにさらに 2 つの読み取りリージョンを追加し、変更内容を保存します。

    📝 一部の手順では、整合性レベルを [強] に変更するように求められます。ただし、リージョン間の距離が 8,000 キロメートル (5,000 マイル) を超えるアカウントの整合性を強にすると、書き込みの待機時間が長くなるため、既定値ではブロックされることに注意してください。 必ず相互の距離が近いリージョンを選んでください。 運用環境でこの機能を有効にするには、サポートにお問い合わせください。

  7. このタスクを続行する前に、レプリケーション タスクが完了するのを待ちます。

    📝 この操作には約 5 〜 10 分かかる場合があり、[既定の整合性] ウィンドウに移動します。

  8. リソース ブレードで、[既定の整合性] ウィンドウに移動します。

  9. [既定の整合性] ウィンドウで、[強固] オプションを選択し、変更を [保存] します。

  10. このタスクを続行する前に、既定の整合性レベルの変更が保持されるまで待ちます。

  11. リソース ブレードで、[データ エクスプローラー] ペインに移動します。

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

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

    設定 Value
    データベース ID 新規作成 | cosmicworks
    コンテナー間でスループットを共有する 選択しない
    コンテナー ID products
    パーティション キー /categoryId
    コンテナーのスループット 手動 | 400

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

  15. [データ エクスプローラー] ペインで、cosmicworksデータベース ノード、products コンテナー ノードの順に展開してから、[項目] を選択します。

  16. [データ エクスプローラー] ペインのまま、コマンド バーから [新しい項目] を選択します。 エディターで、プレースホルダーの JSON 項目を次の内容に置き換えます。

     {
   "id": "7d9273d9-5d91-404c-bb2d-126abb6e4833",
   "categoryId": "78d204a2-7d64-4f4a-ac29-9bfc437ae959",
   "categoryName": "Components, Pedals",
   "sku": "PD-R563",
   "name": "ML Road Pedal",
   "price": 62.09
 }

  17. コマンド バーから [保存] を選択して、JSON 項目を追加します。

  18. [項目] タブで、[項目] ペインの新しい項目を確認します。

  19. リソース ブレードで、[キー] ペインに移動します。

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

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

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

  21. Visual Studio Code に戻ります。

SDK から Azure Cosmos DB for NoSQL アカウントに接続する

新しく作成したアカウントの資格情報を使用して、SDK クラスに接続し、新しいデータベースとコンテナー インスタンスを作成します。 次に、データ エクスプローラーを使用して、Azure portal でインスタンスが存在することを検証します。

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

  2. 21-sdk-consistency-model フォルダーのコンテキスト メニューを開き、[統合ターミナルで開く] を選択して新しいターミナル インスタンスを開きます。

    📝 このコマンドを実行すると、開始ディレクトリが 21-sdk-consistency-model フォルダーに既に設定されているターミナルが開きます。

  3. dotnet build コマンドを使用してプロジェクトをビルドします。

     dotnet build

    📝 コンパイラから、endpoint および key 変数は現在使用されていないという警告が表示される場合があります。 これらの変数はこのタスクで使用しますので、この警告は無視しても問題ありません。

  4. 統合ターミナルを閉じます。

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

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

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

    📝 [Microsoft.Azure.Cosmos][nuget.org/packages/microsoft.azure.cosmos/3.49.0] ライブラリは、既に NuGet から事前にインポートされています。

  8. endpoint という名前の string 変数を見つけます。 その値を、先ほど作成した Azure Cosmos DB アカウントのエンドポイントに設定します。

     string endpoint = "<cosmos-endpoint>";

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

  9. key という名前の string 変数を見つけます。 その値を、先ほど作成した Azure Cosmos DB アカウントのキーに設定します。

     string key = "<cosmos-key>";

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

  10. script.cs コード ファイルを保存します。

ポイント操作の整合性レベルを構成する

ItemRequestOptions クラスには、要求ごとの構成プロパティが含まれています。 このクラスを使用すると、整合性レベルを現在の既定である強固な整合性から最終的な整合性に緩和できます。

  1. id という名前の文字列変数を、値 7d9273d9-5d91-404c-bb2d-126abb6e4833 で作成します。

     string id = "7d9273d9-5d91-404c-bb2d-126abb6e4833";

  2. categoryId という名前の文字列変数を、値 78d204a2-7d64-4f4a-ac29-9bfc437ae959 で作成します。

     string categoryId = "78d204a2-7d64-4f4a-ac29-9bfc437ae959";

  3. コンストラクター パラメーターとして categoryId 変数を渡して、partitionKey という名前の PartitionKey 型の変数を作成します。

     PartitionKey partitionKey = new (categoryId);

  4. メソッド パラメーターとして id および partitionkey 変数を渡し、ジェネリック型として Product を使用して、container 変数の ReadItemAsync<> 汎用メソッドを非同期に呼び出し、結果を ItemResponse<Product> 型の response という名前の変数に格納します。

     ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey);

  5. Console.WriteLine 静的メソッドを呼び出して、書式付きの出力文字列を使用して、要求料金を出力します。

     Console.WriteLine($"STRONG Request Charge:\t{response.RequestCharge:0.00} RUs");

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

     using Microsoft.Azure.Cosmos;

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

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Container container = client.GetContainer("cosmicworks", "products");
    
 string id = "7d9273d9-5d91-404c-bb2d-126abb6e4833";
    
 string categoryId = "78d204a2-7d64-4f4a-ac29-9bfc437ae959";
 PartitionKey partitionKey = new (categoryId);
    
 ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey);
    
 Console.WriteLine($"STRONG Request Charge:\t{response.RequestCharge:0.00} RUs");

  7. script.cs コード ファイルを保存します。

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

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

     dotnet run

  10. ターミナルからの出力を確認します。 要求料金 (RU 単位) をコンソールに出力する必要があります。

    📝 現在の要求料金は 2 RUs になっているはずです。 これは、強力な一貫性では、最新の書き込みが行われるように、少なくとも 2 つのレプリカからの読み取りが必要であるためです。

  11. 統合ターミナルを閉じます。

  12. script.cs コード ファイルのエディター タブに戻ります。

  13. 次のコード行を削除します。

     ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey);
    
 Console.WriteLine($"Request Charge:\t{response.RequestCharge:0.00} RUs");

  14. Itemrequestoptions 型の options という名前の新しい変数を作成し、ConsistencyLevel プロパティを ConsistencyLevel 列挙値に設定します。

     ItemRequestOptions options = new()
 { 
     ConsistencyLevel = ConsistencyLevel.Eventual 
 };

  15. メソッド パラメーターとして id、partitionkey、および options 変数を渡し、ジェネリック型として Product を使用して、container 変数の ReadItemAsync<> 汎用メソッドを非同期に呼び出し、結果を ItemResponse<Product> 型の response という名前の変数に格納します。

     ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey, requestOptions: options);

  16. Console.WriteLine 静的メソッドを呼び出して、書式付きの出力文字列を使用して、要求料金を出力します。

     Console.WriteLine($"EVENTUAL Request Charge:\t{response.RequestCharge:0.00} RUs");

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

     using Microsoft.Azure.Cosmos;

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

 CosmosClient client = new CosmosClient(endpoint, key);
    
 Container container = client.GetContainer("cosmicworks", "products");
    
 string id = "7d9273d9-5d91-404c-bb2d-126abb6e4833";
    
 string categoryId = "78d204a2-7d64-4f4a-ac29-9bfc437ae959";
 PartitionKey partitionKey = new (categoryId);

 ItemRequestOptions options = new()
 { 
     ConsistencyLevel = ConsistencyLevel.Eventual 
 };
    
 ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey, requestOptions: options);
    
 Console.WriteLine($"EVENTUAL Request Charge:\t{response.RequestCharge:0.00} RUs");

  18. script.cs コード ファイルを保存します。

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

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

     dotnet run

  21. ターミナルからの出力を確認します。 要求料金 (RU 単位) をコンソールに出力する必要があります。

    📝 現在の要求料金は 1 RUs になっているはずです。 これは、最終的な整合性によって、1 つのレプリカからの読み取りのみが必要になるためです。

  22. 統合ターミナルを閉じます。

  23. Visual Studio Code を閉じます。