チュートリアル: Azure Cosmos DB for NoSQL を使用してグローバル分散を設定する

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

適用対象: NoSQL

この記事では、Azure portal を使用して Azure Cosmos DB グローバル分散を設定し、NoSQL 用 API を使用して接続する方法を説明します。

この記事に含まれるタスクは次のとおりです。

Azure Portal を使用してグローバル分散を構成する
NoSQL 用 API を使用してグローバル分散を構成する

Azure Portal を使用したグローバルデータベースリージョンの追加

Azure Cosmos DB は世界中のすべての Azure リージョンで利用できます。データベースアカウントの既定の一貫性レベルを選択すると、選択した既定の一貫性レベルとグローバル配信の必要性に応じて、1 つまたは複数のリージョンを関連付けることができます。

Azure Portal で、左側のバーの [Azure Cosmos DB] をクリックします。
[Azure Cosmos DB] ページで、変更するデータベースアカウントを選びます。
アカウントのページで、メニューから [データをグローバルにレプリケートする] をクリックします。
[データをグローバルにレプリケートする] ページで、マップ内のリージョンをクリックして、追加または削除するリージョンを選択し、[保存] をクリックします。リージョンを追加するには費用が必要になります。詳細については、価格に関するページまたは「Azure Cosmos DB を使用したデータのグローバル分散」の記事を参照してください。

2 番目のリージョンを追加すると、ポータルの [データをグローバルにレプリケートする] ページで [手動フェールオーバー] オプションが有効になります。このオプションは、フェールオーバープロセスをテストしたり、プライマリ書き込みリージョンを変更したりするために使用できます。 3 番目のリージョンを追加すると、同じページの [フェールオーバーの優先度] オプションが有効になります。これで、読み取りのフェールオーバーの順序を変更できるようになります。

グローバルデータベースリージョンの選択

複数のリージョンを構成する場合、2 つの一般的なシナリオがあります。

エンドユーザーが世界中のどこにいても関係なく、データへの待ち時間の短いアクセスを実現する
ビジネス継続性とディザスターリカバリー (BCDR) のためにリージョンの回復性を追加する

エンドユーザーの短い待ち時間の実現のため、アプリケーションのユーザーが存在する場所に対応するリージョンに、アプリケーションと Azure Cosmos DB の両方をデプロイすることをお勧めします。

BCDR のため、「Azure のリージョン間レプリケーション: ビジネス継続性とディザスターリカバリー」に記載されているリージョンペアに基づいてリージョンを追加することをお勧めします。

NoSQL 用 API を使用して優先リージョンに接続する

グローバル分散を活用するために、クライアントアプリケーションでは、ドキュメントの操作の実行に使用するリージョンの順序付き優先リストを指定できます。 Azure Cosmos DB アカウント構成、現在のリージョンの可用性、指定された優先リストに基づいて、書き込み操作と読み取り操作を実行する SQL SDK によって最適なエンドポイントが選択されます。

この優先リストは、SQL SDK を使用して接続を初期化する際に指定されます。 SDK は、Azure リージョンの順序指定済みリストである省略可能なパラメーター PreferredLocations を受け取ります。

SDK は、すべての書き込みを現在の書き込みリージョンに自動的に送信します。読み取りはすべて、PreferredLocations リストで使用可能な最初のリージョンに送信されます。要求が失敗すると、クライアントはリストにある次のリージョンを試します。

SDK は、優先される場所で指定されたリージョンからの読み取りのみを試みます。このため、たとえば 4 つのリージョンで Azure Cosmos DB アカウントが利用できるものの、クライアントが PreferredLocations 内で読み取り (非書き込み) リージョンを 2 つだけ指定している場合には、PreferredLocations で指定されていない読み取りリージョンからは読み取りが行われません。 PreferredLocations リストで指定された読み取りリージョンが利用できない場合は、書き込みリージョンから読み取りが行われます。

アプリケーションは、WriteEndpoint と ReadEndpoint の 2 つのプロパティをチェックすることで、SDK によって選択された現在の書き込みエンドポイントと読み取りエンドポイントを確認できます。これらのプロパティは SDK バージョン 1.8 以上で利用可能です。 PreferredLocations プロパティが設定されていない場合、すべての要求が現在の書き込みリージョンから処理されます。

優先される場所を指定せずに setCurrentLocation メソッドを使用すると、SDK は、クライアントが実行されている現在のリージョンに基づいて、優先される場所を自動的に設定します。 SDK は、各リージョンを、現在のリージョンとの距離に基づいて並べ替えます。

.NET SDK

SDK はコードに変更を加えることなく使用できます。この場合、SDK は読み取りと書き込みの両方を現在の書き込みリージョンに自動的に転送します。 .NET SDK のバージョン 1.8 以降では、DocumentClient コンストラクターの ConnectionPolicy パラメーターに Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations という名前のプロパティがあります。このプロパティは、コレクション型 <string> であり、リージョン名のリストを含んでいる必要があります。文字列値は、「Azure のリージョン」ページのリージョン名の列に従って書式設定されます。先頭文字の前と末尾の文字の後ろにはスペースはありません。

現在の書き込みエンドポイントと読み取りエンドポイントはそれぞれ、DocumentClient.WriteEndpoint と DocumentClient.ReadEndpoint で確認することができます。

Note

エンドポイントの URL は、有効期間が長い定数と見なさないでください。これらは任意のタイミングでサービスによって更新される可能性があります。 SDK はこの変更を自動的に処理します。

.NET SDK V2
.NET SDK V3

.NET V2 SDK を使用している場合は、PreferredLocations プロパティを使用して、優先リージョンを設定します。

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference
// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

または、SetCurrentLocation プロパティを使用して、近接度に基づいて優先される場所が選択されるようにすることもできます。

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

.NET V3 SDK を使用している場合は、ApplicationPreferredRegions プロパティを使用して、優先リージョンを設定します。

CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
options.ApplicationPreferredRegions = new List<string> {Regions.WestUS, Regions.WestUS2};

CosmosClient client = new CosmosClient(endpoint, credential, options);

または、ApplicationRegion プロパティを使用して、近接度に基づいて優先される場所が選択されるようにすることもできます。

CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
// If the application is running in West US
options.ApplicationRegion = Regions.WestUS;

CosmosClient client = new CosmosClient(endpoint, tokenCredential, options);

Node.js と JavaScript

Note

Node.js/JavaScript のコード例を以下に示します。

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient({ endpoint, aadCredentials: tokenCredential, connectionPolicy: { preferredLocations } });

Python SDK

次のコードは、Python SDK を使用して優先される場所を設定する方法を示しています。

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, credential=token_credential, connectionPolicy)

Java V4 SDK

次のコードは、Java SDK を使用して優先される場所を設定する方法を示しています。

非同期
同期

ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildClient();

Spark 3 コネクタ

spark.cosmos.preferredRegionsList の構成を使って、優先リージョンリストを定義できます。次はその例です。

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

REST

データベースアカウントが複数リージョンで利用できるようになったら、クライアントは URI https://{databaseaccount}.documents.azure.com/ に対して GET 要求を実行してその可用性を照会できます。

リージョンのほか、そのリージョンに対応するレプリカの Azure Cosmos DB エンドポイント URI がリストとしてサービスによって返されます。現在の書き込みリージョンが応答に示されます。クライアントはその後、次のようにそれ以降のすべての REST API 要求に対して適切なエンドポイントを選択できます。

応答の例

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}

PUT 要求、POST 要求、DELETE 要求はすべて、示された書き込み URI に送信されます
すべての GET 要求とその他の読み取り専用の要求 (クエリなど) は、クライアントによって選択された任意のエンドポイントに送信できます。

読み取り専用のリージョンへの書き込み要求は失敗し、HTTP エラーコード 403 ("許可されていません") が表示されます。

クライアントの最初の検出フェーズの後に書き込みリージョンが変更された場合、以前の書き込みリージョンへの以降の書き込みは失敗し、HTTP エラーコード 403 ("許可されていません") が返されます。クライアントはその後、更新された書き込みリージョンを把握するためにリージョンのリストをもう一度取得する必要があります。

このチュートリアルはこれで終わりです。 Azure Cosmos DB の一貫性レベルに関する記事を読んで、グローバルにレプリケートされたアカウントの整合性を管理する方法について確認できます。また、Azure Cosmos DB におけるグローバルデータベースレプリケーションの動作の詳細については、Azure Cosmos DB を使用したデータのグローバル分散に関する記事を参照してください。

次のステップ

このチュートリアルでは、次の手順を行いました。

Azure Portal を使用してグローバル分散を構成する
NoSQL 用 API を使用してグローバル分散を構成する

これで次のチュートリアルに進むことができます。Azure Cosmos DB ローカルエミュレーターを使用してローカルで開発する方法について学びます。

エミュレーターを使用したローカル開発

Azure Cosmos DB への移行のための容量計画を実行しようとしていますか? 容量計画のために、既存のデータベースクラスターに関する情報を使用できます。

既存のデータベースクラスター内の仮想コアとサーバーの数のみがわかっている場合は、仮想コア数または仮想 CPU 数を使用した要求ユニットの見積もりに関するページを参照してください
現在のデータベースワークロードに対する通常の要求レートがわかっている場合は、Azure Cosmos DB Capacity Planner を使用した要求ユニットの見積もりに関するページを参照してください

次の方法で共有

チュートリアル: Azure Cosmos DB for NoSQL を使用してグローバル分散を設定する

Azure Portal を使用したグローバルデータベースリージョンの追加

グローバルデータベースリージョンの選択

NoSQL 用 API を使用して優先リージョンに接続する

.NET SDK

Node.js と JavaScript

Python SDK

Java V4 SDK

Spark 3 コネクタ

REST

次のステップ

フィードバック

その他のリソース

次の方法で共有

チュートリアル: Azure Cosmos DB for NoSQL を使用してグローバル分散を設定する

Azure Portal を使用したグローバル データベース リージョンの追加

グローバル データベース リージョンの選択

NoSQL 用 API を使用して優先リージョンに接続する

.NET SDK

Node.js と JavaScript

Python SDK

Java V4 SDK

Spark 3 コネクタ

REST

次のステップ

フィードバック

その他のリソース

Azure Portal を使用したグローバルデータベースリージョンの追加

グローバルデータベースリージョンの選択