接続モードを構成する

  • 7 分

CosmosClientOptions クラスには、クライアントがアカウントに接続するときに構成できるさまざまなオプションが用意されています。 このようなオプションには次のものが含まれますが、これらに限定されません。

  • アカウントへの接続に使用されるモード
  • クライアント インスタンス専用のカスタムの整合性レベル
  • 優先するアカウント リージョン

既定のクライアント オプションのオーバーライド

CosmosClient クラスを使用して Azure Cosmos DB アカウントに接続する場合、クライアントが行う前提条件がいくつかあります。

  • アカウントの最初の書き込み可能な (プライマリ) リージョンに接続する必要がある
  • 読み取り要求でアカウントの既定の整合性レベルを使用する
  • 要求のデータ ノードに直接接続する

注

他にも、ここには記載されていない仮定があります。 これらの前提条件は、 CosmosClient クラスを使用して構成することもできます。

クライアントを構成するには、CosmosClientOptions クラスのインスタンスを作成し、CosmosClient コンストラクターに最後のパラメーターとして渡す必要があります。 認証に Microsoft Entra ID マネージド ID を使用すると、接続文字列やキーなどのシークレットを公開することなく、Azure Cosmos DB に安全にアクセスできます。

Microsoft Entra マネージド ID を使用した例は次のとおりです。

using Azure.Identity;
using Microsoft.Azure.Cosmos;

// Configure the account endpoint
string accountEndpoint = "https://<youraccountname>.documents.azure.com:443/";

// Use DefaultAzureCredential for Azure Entra Managed Identity authentication
DefaultAzureCredential credential = new DefaultAzureCredential();

// Initialize CosmosClient with endpoint and credential
CosmosClient client = new (accountEndpoint, credential);

接続モードの変更

CosmosClientOptions クラス内で、ConnectionMode プロパティを 2 つの列挙可能な値のいずれかに設定できます。

価値 説明
ゲートウェイ すべての要求はプロキシとして Azure Cosmos DB ゲートウェイ経由でルーティングされます
直接 このゲートウェイは、データ ノードに直接接続するために、初期化の際とアドレスのキャッシュでのみ使用されます

既定の設定では、 直接接続 モードを使用します。 この例では、既定の設定を使用するようにクライアントを構成します。

CosmosClientOptions options = new ()
{
    ConnectionMode = ConnectionMode.Direct
};

必要に応じて、ゲートウェイを要求のプロキシとして常に使用するようにクライアントを構成することもできます。 この例では、 ゲートウェイ 接続モードを使用するようにクライアントを構成します。

CosmosClientOptions options = new ()
{
    ConnectionMode = ConnectionMode.Gateway
};

現在の整合性レベルの変更

すべての Azure Cosmos DB for NoSQL アカウントには、既定の整合性レベルが構成されています。 個々のクライアントでは、クライアントで行われたすべての読み取り要求に対して異なる整合性レベルを構成できます。 この例は、クライアントが最終的整合性を使用するように構成されていることを示しています。

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

ConsistencyLevel 列挙には、次のような複数の潜在的な値があります。

  • 有界整合性制約
  • ConsistentPrefix
  • 最終的
  • セッション
  • 厳密

ヒント

ConsistencyLevel 設定は、読み取りの整合性レベルを弱めるためだけに使用されます。 これを強くしたり書き込みに適用したりすることはできません。

優先するアプリケーション リージョンの設定

既定では、最初の書き込み可能なリージョンがクライアントによって要求に使用されます。 このリージョンは通常、プライマリ リージョンと呼ばれます。 CosmosClientOptions.ApplicationRegion または CosmosClientOptions.ApplicationPreferredRegions を使用して、この動作をオーバーライドできます。

ApplicationRegion プロパティは、クライアントが操作のために接続する単一の優先リージョンを設定します。 構成されたリージョンが使用できない場合、クライアントによって、アカウントに設定されているフォールバック優先順位リストが既定に設定され、使用する次のリージョンが決定されます。 この例では、優先リージョンは 米国西部に構成されています。

CosmosClientOptions options = new ()
{
    ApplicationRegion = "westus"
};

ヒント

アカウントがマルチリージョン書き込み用に構成されていない場合、クライアントでは書き込み操作に対して常に単一の書き込み可能なリージョンを使用します。この設定によって読み取り操作のみが影響を受けます。

操作に使用するクライアントのカスタム フェールオーバー/優先度リストを作成する場合は、 ApplicationPreferredRegions プロパティをリージョンの一覧と共に使用できます。 この例では、最初に 米国西部 、次に 米国東部を試用するように構成されたカスタム リストを使用します。

CosmosClientOptions options = new CosmosClientOptions()
{
    ApplicationPreferredRegions = new List<string> { "westus", "eastus" }
};

Python SDK の CosmosClient クラスには、アカウントに接続するときのクライアントの動作をカスタマイズするように構成できるオプションがいくつか用意されています。 このようなオプションには次のものが含まれますが、これらに限定されません。

  • クライアント インスタンス専用のカスタムの整合性レベル
  • 優先するアカウント リージョン

既定のクライアント オプションのオーバーライド

クライアントが CosmosClient クラスを使用して Azure Cosmos DB アカウントに接続すると、次の既定の前提条件が行われます。

  • クライアントは、アカウントの最初の書き込み可能な (プライマリ) リージョンに接続します。
  • クライアントは、読み取り要求に既定の整合性レベルを使用します。
  • クライアントは ゲートウェイ 接続モードを使用します (Python SDK では直接モードを使用できません)。

注

その他の前提条件もあり、必要に応じて構成できます。 このセクションでは、最も一般的な構成について説明します。

これらのオプションをカスタマイズするには、構成ディクショナリまたはキーワード引数を CosmosClient コンストラクターに渡します。 次の例では、さまざまなオプションを使用してクライアントを構成する方法を示します。

現在の整合性レベルの変更

すべての Azure Cosmos DB for NoSQL アカウントには、既定の整合性レベルが構成されています。 Python SDK を使用すると、クライアントで行われたすべての読み取り要求に対して異なる整合性レベルを構成できます。 この例では、 最終的 な整合性を使用するようにクライアントを構成します。

from azure.cosmos import CosmosClient, ConsistencyLevel

client = CosmosClient(
    url="https://dp420.documents.azure.com:443/",
    credential="fDR2ci9QgkdkvERTQ==",
    consistency_level=ConsistencyLevel.Eventual
)

ConsistencyLevel クラスには、次のようないくつかのオプションが含まれています。

  • 有界整合性制約
  • 一貫性のあるプレフィックス
  • 最終的
  • セッション
  • 厳密

ヒント

consistency_level設定は、読み取りの整合性レベルを弱めるためにのみ使用できます。 これを強くしたり書き込みに適用したりすることはできません。

優先するアプリケーション リージョンの設定

既定では、クライアントは最初の書き込み可能なリージョンに接続して操作を行います。 preferred_locations パラメーターを使用して優先リージョンを指定できます。 次の例では、優先するリージョンを [米国西部] に設定しています。

client = CosmosClient(
    url="https://dp420.documents.azure.com:443/",
    credential="fDR2ci9QgkdkvERTQ==",
    preferred_locations=["West US"]
)

ヒント

アカウントがマルチリージョン書き込み用に構成されていない場合、クライアントでは書き込み操作に対して常に単一の書き込み可能なリージョンを使用します。この設定によって読み取り操作のみが影響を受けます。

また、カスタム フェールオーバー/優先度リストに優先するリージョンを複数設定することもできます。 この例では、最初に 米国西部 、次に 米国東部を試すクライアントを構成します。

client = CosmosClient(
    url="https://dp420.documents.azure.com:443/",
    credential="fDR2ci9QgkdkvERTQ==",
    preferred_locations=["West US", "East US"]
)

その他の構成オプション

Python SDK では Direct への接続モードの設定はサポートされていませんが、 CosmosClient の構成可能なその他のオプションが含まれています。

  • 再試行ポリシー: 一時的な障害を処理するように再試行ポリシーを構成します。
  • タイムアウト: クライアント操作のカスタム タイムアウトを設定します。
  • ユーザー エージェント: テレメトリと追跡用にユーザー エージェント文字列をカスタマイズします。

カスタム タイムアウト構成を示す例:

client = CosmosClient(
    url="https://dp420.documents.azure.com:443/",
    credential="fDR2ci9QgkdkvERTQ==",
    connection_timeout=10  # Sets a custom connection timeout of 10 seconds
)

JavaScript SDK の CosmosClient クラスには、アカウントに接続するときのクライアントの動作をカスタマイズするように構成できるいくつかのオプションが用意されています。 このようなオプションには次のものが含まれますが、これらに限定されません。

  • クライアント インスタンス専用のカスタムの整合性レベル
  • 優先するアカウント リージョン

既定のクライアント オプションのオーバーライド

クライアントが CosmosClient クラスを使用して Azure Cosmos DB アカウントに接続すると、次の既定の前提条件が行われます。

  • クライアントは、アカウントの最初の書き込み可能な (プライマリ) リージョンに接続します。
  • クライアントは、読み取り要求に既定の整合性レベルを使用します。
  • クライアントは ゲートウェイ 接続モードを使用します (JavaScript SDK では直接モードを使用できません)。

注

その他の前提条件もあり、必要に応じて構成できます。 このセクションでは、最も一般的な構成について説明します。

これらのオプションをカスタマイズするには、構成オブジェクトを CosmosClient コンストラクターに渡します。 次の例では、さまざまなオプションを使用してクライアントを構成する方法を示します。

現在の整合性レベルの変更

すべての Azure Cosmos DB for NoSQL アカウントには、既定の整合性レベルが構成されています。 JavaScript SDK を使用すると、クライアントで行われたすべての読み取り要求に対して異なる整合性レベルを構成できます。 この例では、 最終的 な整合性を使用するようにクライアントを構成します。

const { CosmosClient, ConsistencyLevel } = require("@azure/cosmos");

const client = new CosmosClient({
  endpoint: "https://dp420.documents.azure.com:443/",
  key: "fDR2ci9QgkdkvERTQ==",
  consistencyLevel: ConsistencyLevel.Eventual
});

CosmosClient クラスには、接続文字列と構成オブジェクトの両方を受け入れる省略可能なコンストラクターが含まれています。 consistencyLevel プロパティを設定するには、次の構文を使用できます。

const { CosmosClient, ConsistencyLevel } = require("@azure/cosmos");

const client = new CosmosClient(
  "AccountEndpoint=https://dp420.documents.azure.com:443/;AccountKey=fDR2ci9QgkdkvERTQ==",
  {
    consistencyLevel: ConsistencyLevel.Eventual,
  }
);

consistencyLevel プロパティは、次のいずれかの値に設定できます。

  • 強い
  • バウンディド・ステールネス
  • セッション
  • 最終的
  • ConsistentPrefix

ヒント

consistencyLevel 設定は、読み取りの整合性レベルを弱めるためにのみ使用できます。 これを強くしたり書き込みに適用したりすることはできません。

優先するアプリケーション リージョンの設定

既定では、クライアントは最初の書き込み可能なリージョンに接続して操作を行います。 connectionPolicy プロパティ内で preferredLocations プロパティを使用して、優先リージョンを指定できます。 次の例では、優先するリージョンを [米国西部] に設定しています。

const client = new CosmosClient({
  endpoint: "https://dp420.documents.azure.com:443/",
  key: "fDR2ci9QgkdkvERTQ==",
  connectionPolicy: {
    preferredLocations: ["West US"]
  }
});

ヒント

アカウントがマルチリージョン書き込み用に構成されていない場合、クライアントでは書き込み操作に対して常に単一の書き込み可能なリージョンを使用します。この設定によって読み取り操作のみが影響を受けます。

また、カスタム フェールオーバー/優先度リストに優先するリージョンを複数設定することもできます。 この例では、最初に 米国西部 、次に 米国東部を試すクライアントを構成します。

const client = new CosmosClient({
  endpoint: "https://dp420.documents.azure.com:443/",
  key: "fDR2ci9QgkdkvERTQ==",
  connectionPolicy: {
    preferredLocations: ["West US", "East US"]
  }
});

その他の構成オプション

JavaScript SDK には、 CosmosClient のその他の構成可能なオプションが含まれています。

  • 再試行ポリシー: 一時的な障害を処理するように再試行ポリシーを構成します。
  • タイムアウト: クライアント操作のカスタム タイムアウトを設定します。
  • ユーザー エージェント サフィックス: テレメトリと追跡用にユーザー エージェント文字列をカスタマイズします。

要求のカスタム タイムアウト構成を示す例:

const client = new CosmosClient({
  endpoint: "https://dp420.documents.azure.com:443/",
  key: "fDR2ci9QgkdkvERTQ==",
  connectionPolicy: {
    requestTimeout: 10000 // Sets a custom request timeout of 10 seconds (in milliseconds)
  }
});