チュートリアル:SQL API を使用して Azure Cosmos DB グローバル分散をセットアップする

適用対象: SQL API

この記事では、Azure portal を使用して Azure Cosmos DB グローバル分散をセットアップし、SQL API を使用して接続する方法を説明します。

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

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

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

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

  1. Azure Portal で、左側のバーの [Azure Cosmos DB] をクリックします。

  2. [Azure Cosmos DB] ページで、変更するデータベース アカウントを選びます。

  3. アカウントのページで、メニューから [データをグローバルにレプリケートする] をクリックします。

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

    地図でリージョンをクリックして、リージョンを追加又は削除する

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

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

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

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

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

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

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

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

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

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

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

アプリケーションは、WriteEndpointReadEndpoint の 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 で確認することができます。

注意

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

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

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
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,
    accountKey,
    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);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

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

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

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

Node.js と JavaScript

注意

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

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, key, connectionPolicy: { preferredLocations } });

Python SDK

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

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK

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

Java SDK V4 (Maven com.azure::azure-cosmos) 非同期 API


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

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

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 を使用してグローバル分散を構成する
  • SQL API を使用してグローバル分散を構成する

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

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