Azure Cosmos DB for NoSQL SDK を使用してさまざまなリージョンに接続する

Azure Cosmos DB for NoSQL アカウントの geo 冗長性を有効にすると、SDK を使用して、構成した任意の順序でリージョンからデータを読み取ることができます。この手法は、読み取り要求を、使用可能なすべての読み取りリージョンにわたって配布する場合に役立ちます。

このラボでは、手動で構成するフォールバックの順序で読み取りリージョンに接続するように CosmosClient クラスを構成します。

開発環境を準備する

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

Visual Studio Code を起動します。

📝 Visual Studio Code インターフェイスについてまだよく理解していない場合は、作業の開始に関するドキュメントをご覧ください
コマンドパレットを開き、Git: Clone を実行して、任意のローカルフォルダーに https://github.com/microsoftlearning/dp-420-cosmos-db-dev GitHub リポジトリをクローンします。

💡 Ctrl + Shift + P キーボードショートカットを使用してコマンドパレットを開くことができます。
リポジトリが複製されたら、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 アカウントに接続する際に使用できます。

新しい Web ブラウザーウィンドウまたはタブで、Azure portal (portal.azure.com) に移動します。
ご利用のサブスクリプションに関連付けられている Microsoft 資格情報を使用して、ポータルにサインインします。

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

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

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

デプロイタスクが完了するまで待ってから、このタスクを続行してください。
新しく作成した Azure Cosmos DB アカウントリソースにアクセスし、[データをグローバルにレプリケートする] ペインに移動します。
[データをグローバルにレプリケートする] ペインで、アカウントにさらに 2 つの読み取りリージョンを追加し、変更内容を保存します。
このタスクを続行する前に、レプリケーションタスクが完了するのを待ちます。

📝 この操作には、5 から 10 分ほどかかる場合があります。
書き込み (プライマリ) リージョンと 2 つの読み取りリージョンの名前を記録します。これらのリージョン名は、この演習で後ほど使用します。

📝 たとえば、プライマリリージョンが 北ヨーロッパで、2 つの読み取りセカンダリリージョンが米国東部 2 と南アフリカ北部の場合は、この 3 つの名前をすべてそのまま記録します。
リソースブレードで、[データエクスプローラー] ペインに移動します。
[データエクスプローラー] ペインで、 [新しいコンテナー] を選択します。

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

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

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

[データエクスプローラー] ペインのまま、コマンドバーから [新しい項目] を選択します。エディターで、プレースホルダーの 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
 }

コマンドバーから [保存] を選択して、JSON 項目を追加します。
[項目] タブで、[項目] ペインの新しい項目を確認します。
リソースブレードで、[キー] ペインに移動します。
このペインには、SDK からアカウントに接続するために必要な接続の詳細と資格情報が含まれています。具体的な内容は次のとおりです。
1. [URI] フィールドに注目します。このエンドポイントの値は、この演習で後ほど使用します。
2. [主キー] フィールドに注目してください。このキーの値は、この演習で後ほど使用します。
Visual Studio Code に戻ります。

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

新しく作成したアカウントの資格情報を使用して、SDK クラスに接続し、異なるリージョンのデータベースとコンテナーインスタンスにアクセスします。

[エクスプローラー] ウィンドウで、20-sdk-regions フォルダーを参照します。
20-sdk-regions フォルダーのコンテキストメニューを開き、[統合ターミナルで開く] を選択して新しいターミナルインスタンスを開きます。

📝 このコマンドを実行すると、ターミナルが開き、開始ディレクトリが既に 20-sdk-regions フォルダーに設定されています。
dotnet build コマンドを使用してプロジェクトをビルドします。
```
 dotnet build
```
📝 コンパイラから、endpoint および key 変数は現在使用されていないという警告が表示される場合があります。これらの変数はこのタスクで使用しますので、この警告は無視しても問題ありません。
統合ターミナルを閉じます。
20-sdk-regions フォルダー内の script.cs コードファイルを開きます。

📝 [Microsoft.Azure.Cosmos][nuget.org/packages/microsoft.azure.cosmos/3.22.1] ライブラリは、既に NuGet から事前にインポートされています。
endpoint という名前の string 変数を見つけます。その値を、先ほど作成した Azure Cosmos DB アカウントのエンドポイントに設定します。
```
 string endpoint = "<cosmos-endpoint>";
```
📝 たとえば、ご自分のエンドポイントが https://dp420.documents.azure.com:443/ の場合、C# ステートメントは string endpoint = “https://dp420.documents.azure.com:443/”; になります。
key という名前の string 変数を見つけます。その値を、先ほど作成した Azure Cosmos DB アカウントのキーに設定します。
```
 string key = "<cosmos-key>";
```
📝 たとえば、キーが fDR2ci9QgkdkvERTQ== の場合、C# ステートメントは string key = “fDR2ci9QgkdkvERTQ==”; になります。
script.cs コードファイルを保存します。

優先リージョンリストを使用して .NET SDK を構成する

CosmosClientOptions クラスには、SDK を使用して接続するリージョンのリストを構成するためのプロパティが用意されています。リストは、構成した順序で各リージョンへの接続を試行するように、フェールオーバー優先度順に並べます。

List<string> ジェネリック型の新しい変数を作成して、アカウントで構成したリージョンのリストを 3 番目のリージョンから開始し、1 番目の (プライマリ) リージョンで終了するように含めます。たとえば、米国西部リージョンに Azure Cosmos DB for NoSQL アカウントを作成し、次に南アフリカ北部を追加し、最後に東アジアを追加した場合、リスト変数は次のようにします。
```
 List<string> regions = new()
 {
     "East Asia",
     "South Africa North",
     "West US"
 };
```
💡 代わりに、Microsoft.Azure.Cosmos.Regions 静的クラスを使用して、異なる Azure リージョンの組み込みの文字列プロパティを含めることもできます。
options という名前の CosmosClientOptions クラスの新しいインスタンスを作成し、ApplicationPreferredRegions プロパティを region 変数に設定します。
```
 CosmosClientOptions options = new () 
 { 
     ApplicationPreferredRegions = regions
 };
```
コンストラクターパラメーターとして endpoint、key、および options 変数を渡して、client という名前の CosmosClient クラスの新しいインスタンスを作成します。
```
 using CosmosClient client = new (endpoint, key, options); 
```
client 変数の GetContainer メソッドを使用し、データベースの名前 (cosmicworks) とコンテナーの名前 (products) を使って既存のコンテナーを取得します。
```
 Container container = client.GetContainer("cosmicworks", "products");
```
container 変数の ReadItemAsync メソッドを使用して、サーバーから特定の項目を取得し、Null 許容の ItemResponse 型のresponse という名前の変数に結果を格納します。
```
 ItemResponse<dynamic> response = await container.ReadItemAsync<dynamic>(
     "7d9273d9-5d91-404c-bb2d-126abb6e4833",
     new PartitionKey("78d204a2-7d64-4f4a-ac29-9bfc437ae959")
 );
```

Console.WriteLine 静的メソッドを呼び出して、現在の項目識別子と JSON 診断データを出力します。

 Console.WriteLine($"Item Id:\t{response.Resource.Id}");
 Console.WriteLine($"Response Diagnostics JSON");
 Console.WriteLine($"{response.Diagnostics}");

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

 using Microsoft.Azure.Cosmos;

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

 List<string> regions = new()
 {
     "<read-region-2>",
     "<read-region-1>",
     "<write-region>"
 };
    
 CosmosClientOptions options = new () 
 { 
     ApplicationPreferredRegions = regions
 };
    
 using CosmosClient client = new(endpoint, key, options);
    
 Container container = client.GetContainer("cosmicworks", "products");
    
 ItemResponse<dynamic> response = await container.ReadItemAsync<dynamic>(
     "7d9273d9-5d91-404c-bb2d-126abb6e4833",
     new PartitionKey("78d204a2-7d64-4f4a-ac29-9bfc437ae959")
 );
    
 Console.WriteLine($"Item Id:\t{response.Resource.Id}");
 Console.WriteLine("Response Diagnostics JSON");
 Console.WriteLine($"{response.Diagnostics}");

script.cs コードファイルを保存します。
Visual Studio Code で、20-sdk-regions フォルダーのコンテキストメニューを開き、[統合ターミナルで開く] を選択して新しいターミナルインスタンスを開きます。
dotnet run コマンドを使用して、プロジェクトをビルドして実行します。
```
 dotnet run
```
ターミナルからの出力を確認します。コンソール出力にコンテナーの名前と JSON 診断データが出力されているはずです。
JSON 診断データを確認します。 HttpResponseStats という名前のプロパティと RequestUri という名前の子プロパティを検索します。このプロパティの値は、このラボで先ほど構成した名前とリージョンが含まれる URI のはずです。

📝 たとえば、アカウント名が dp420 で、最初に構成したリージョンが東アジアの場合、JSON ロパティの値は、dp420-eastasia.documents.azure.com/dbs/cosmicworks/colls/products になります。
統合ターミナルを閉じます。
Visual Studio Code を閉じます。

Azure Cosmos DB for NoSQL SDK を使用してさまざまなリージョンに接続する

開発環境を準備する

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

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

優先リージョン リストを使用して .NET SDK を構成する

優先リージョンリストを使用して .NET SDK を構成する