次の方法で共有

Azure Cosmos DB Java SDK v4 の接続構成を調整する

  • 適用対象: ✅ NoSQL

Important

この記事のパフォーマンスに関するヒントは、Azure Cosmos DB Java SDK v4 のみを対象としています。 詳細については、Azure Cosmos DB Java SDK v4 リリース ノート、 Maven リポジトリ、Azure Cosmos DB Java SDK v4 トラブルシューティング ガイド を参照してください。 v4 より古いバージョンを現在使用している場合は、v4 へのアップグレードに関するヘルプについては、 Azure Cosmos DB Java SDK v4 への移行 ガイドを参照してください。

Azure Cosmos DB は、高速で柔軟性に優れた分散データベースです。待機時間とスループットが保証されており、シームレスにスケーリングできます。 Azure Cosmos DB でデータベースをスケーリングするために、アーキテクチャを大きく変更したり、複雑なコードを記述したりする必要はありません。 スケールアップとスケールダウンは、API 呼び出しか SDK メソッド呼び出しを 1 回行うだけで簡単に実行できます。 ただし、Azure Cosmos DB にはネットワーク呼び出しを介してアクセスされるため、Azure Cosmos DB Java SDK v4 を使用するときにピーク パフォーマンスを実現するために調整できる接続構成があります。

接続の構成

注

Azure Cosmos DB Java SDK v4 では、ほとんどのワークロードでデータベースのパフォーマンスを向上させるには 、直接モード が最適です。

さまざまな接続オプションについては、接続モードに関する記事を参照してください。

直接接続モード

Java SDK の既定の接続モードは直接です。 Azure Cosmos DB Java SDK v4 を使用する場合、直接モードの Azure Cosmos DB 要求は TCP 経由で行われます。 内部ダイレクト モードでは、特別なアーキテクチャを使用して、ネットワーク リソースを動的に管理し、最適なパフォーマンスを得ます。 ダイレクト モードで使用されるクライアント側アーキテクチャにより、予測可能なネットワーク使用率と Azure Cosmos DB レプリカへの多重化アクセスが可能になります。 アーキテクチャの詳細については、直接モード接続アーキテクチャを参照してください。

次に示すように 、directMode() メソッドを使用して、クライアント ビルダーで接続モードを構成できます。 既定の設定でダイレクト モードを構成するには、引数を指定せずに directMode() メソッドを呼び出します。 直接モードの接続設定をカスタマイズするには、 DirectConnectionConfig を directMode() API に渡します。

Java SDK V4 (Maven com.azure::azure-cosmos) Async API


/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildAsyncClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildAsyncClient();

/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildAsyncClient();

/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildAsyncClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildAsyncClient();

直接接続モードのカスタマイズ

既定以外のダイレクト モードの動作が必要な場合は、 DirectConnectionConfig インスタンスを作成してそのプロパティをカスタマイズしてから、カスタマイズしたプロパティ インスタンスを Azure Cosmos DB クライアント ビルダーの directMode() メソッドに渡します。

これらの構成設定は、前に説明した基になる Direct モード アーキテクチャの動作を制御します。

最初の手順として、ここで推奨される次の構成設定を使用します。 これらの DirectConnectionConfig オプションは高度な構成設定であり、予期しない方法で SDK のパフォーマンスに影響する可能性があります。トレードオフを理解し、必要な場合を除き、ユーザーは変更しないことをお勧めします。 この特定の問題に関する問題が発生した場合は、 Azure Cosmos DB チーム にお問い合わせください。

構成オプション 既定値 推奨 詳細
アイドル接続タイムアウト (idleConnectionTimeout) "PT0" (ゼロ) "PT0" (ゼロ) これは、エンドポイント/バックエンド ノード (レプリカを表す) への 単一接続 のアイドル接続タイムアウト時間を表します。 既定では、SDK はバックエンド ノードへのアイドル状態の接続を自動的に閉じません。
idleEndpointTimeout "PT1H" "PT1H" これは、エンドポイント/バックエンド ノード (レプリカを表す) の 接続プール のアイドル接続タイムアウト時間を表します。 既定では、特定のエンドポイント/バックエンド ノードに対する受信要求がない場合、SDK は 1 時間後にそのエンドポイント/バックエンド ノードへの接続プール内のすべての接続を閉じて、ネットワーク リソースと I/O コストを節約します。 スパースまたは散発的なトラフィック パターンの場合は、SDK が頻繁に接続を開く必要がないように、この値を 6 時間、12 時間、さらには 24 時間などの高い数値に設定することをお勧めします。 ただし、これはネットワーク リソースを利用し、特定の時点で開いたままの接続の数が多くなります。 これが「ゼロ」に設定されている場合、待機状態のエンドポイントチェックは無効になります。
maxConnectionsPerEndpoint "130" "130" これは、エンドポイント/バックエンド ノード (レプリカを表す) の 接続プール の上限サイズを表します。 SDK は、受信した同時要求に基づいて、オンデマンドでエンドポイント/バックエンド ノードへの接続を作成します。 既定では、必要に応じて、SDK はエンドポイント/バックエンド ノードへの最大 130 個の接続を作成します。 (注: SDK では、これらの 130 個の接続は事前に作成されません)。
maxRequestsPerConnection "30" 30 これは、特定のエンドポイント/バックエンド ノード (レプリカを表す) の 1 つの接続 でキューに登録できる要求の最大数の上限サイズを表します。 SDK は、受信した同時要求に基づいて、エンドポイント/バックエンド ノードへの 1 つの接続に対する要求をオンデマンドでキューに入れます。 既定では、必要に応じて、SDK は特定のエンドポイント/バックエンド ノードに対して 1 つの接続に対して最大 30 個の要求をキューに入れます。 (注: SDK では、これらの 30 個の要求を 1 つの接続に先行してキューに登録しません)。
接続タイムアウト "PT5S" "~PT1S" これは、エンドポイント/バックエンド ノードを使用して 1 つの接続 を確立するための接続確立タイムアウト時間を表します。 既定では、SDK は接続の確立を最大 5 秒間待機してからエラーをスローします。 TCP 接続確立では、接続確立時間の待機時間を長くする マルチステップ ハンドシェイク が使用されるため、ネットワーク帯域幅と環境設定に従ってこの値を設定することをお勧めします。 注: ~PT1S のこの推奨事項は、Cosmos DB アカウントの併置されたリージョンにデプロイされたアプリケーションにのみ適用されます。
ネットワークリクエストタイムアウト (networkRequestTimeout) "PT5S" "PT5S" これは、 1 つの要求のネットワーク タイムアウト期間を表します。 SDK は、リクエストがネットワーク接続に書き込まれた後、サービス応答を受け取るまでの最大時間を待機します。 SDK では、1 秒 (最小) から 10 秒 (最大) の値のみが許可されます。 値を大きすぎると、再試行回数が少なくなり、再試行による成功の可能性が低下する可能性があります。

ゲートウェイ接続モード

データベースやコンテナー CRUD などのコントロール プレーン操作では 、常に ゲートウェイ モードが利用されます。 ユーザーがデータ プレーン操作用に Direct モードを構成した場合でも、コントロール プレーンとメタデータ操作では既定のゲートウェイ モード設定が使用されます。 これはほとんどのユーザーに適しています。 ただし、データ プレーン操作とコントロール プレーン ゲートウェイ モード パラメーターのチューニングに Direct モードを使用するユーザーは、次の directMode() オーバーライドを使用できます。

Java SDK V4 (Maven com.azure::azure-cosmos) Async API


/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

ゲートウェイ接続モードのカスタマイズ

既定以外のゲートウェイ モードの動作が必要な場合は、 GatewayConnectionConfig インスタンスを作成してそのプロパティをカスタマイズし、カスタマイズしたプロパティ インスタンスを Azure Cosmos DB クライアント ビルダーの directMode() オーバーライド メソッドまたは gatewayMode() メソッドに渡します。

最初の手順として、ここで推奨される次の構成設定を使用します。 これらの GatewayConnectionConfig オプションは高度な構成設定であり、予期しない方法で SDK のパフォーマンスに影響する可能性があります。トレードオフを理解し、必要な場合を除き、ユーザーは変更しないことをお勧めします。 この特定の問題に関する問題が発生した場合は、 Azure Cosmos DB チーム にお問い合わせください。

構成オプション 既定値 推奨 詳細
maxConnectionPoolSize "1000" "1000" これは、基になる http クライアントの接続プール サイズの上限サイズを表します。これは、ゲートウェイ モードへの要求に対して SDK によって作成される接続の最大数です。 SDK は、ゲートウェイに要求を送信するときに、これらの接続を再利用します。
アイドル接続タイムアウト (idleConnectionTimeout) "PT60S" "PT60S" これは、ゲートウェイへの 1 つの接続 のアイドル接続タイムアウト時間を表します。 この時間が経過すると、接続は自動的に閉じられ、接続プールから削除されます。

次のステップ

Java SDK のパフォーマンスに関するヒントの詳細については、「Azure Cosmos DB Java SDK v4 のパフォーマンスに関するヒント」を参照してください。

スケーリングと高パフォーマンスのためのアプリケーションの設計について詳しくは、「Azure Cosmos DB でのパーティション分割とスケーリング」をご覧ください。

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

  • Last updated on