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

[アーティクル]
08/15/2024

適用対象: NoSQL

重要

この記事のパフォーマンスに関するヒントは、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 を使用するときに最高のパフォーマンスを実現するために、接続構成を調整することができます。

接続の構成

Note

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) 非同期 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();

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


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

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

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

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

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

/* 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);

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

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

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

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

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

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

構成オプション	Default	推奨	詳細
idleConnectionTimeout	"PT0" (ゼロ)	"PT0" (ゼロ)	これは、エンドポイント/バックエンドノード (レプリカを表す) への "1 つの接続" のアイドル接続タイムアウト時間を表します。既定の 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 では、1 つの接続に対するこれら 30 個の要求は事前にキューに格納されません)。
connectTimeout	"PT5S"	"~PT1S"	これは、エンドポイント/バックエンドノードとの間で確立される "1 つの接続" の接続確立タイムアウト時間を表します。既定の SDK では、接続の確立まで最大 5 秒間待機してからエラーをスローします。 TCP 接続確立では、接続確立時間の待機時間が長い複数ステップのハンドシェイクが使用されるため、お客様はネットワーク帯域幅と環境設定に従ってこの値を設定することをお勧めします。注: ~PT1S に関するこの推奨事項は、Cosmos DB アカウントの併置リージョンにデプロイされたアプリケーションにのみ適用されます。
networkRequestTimeout	"PT5S"	"PT5S"	これは、"1 つの要求" のネットワークタイムアウト時間を表します。 SDK では、要求がネットワーク接続に書き込まれた後、サービス応答が使用されるまで、最大の時間待機します。 SDK では、1 秒 (最小) から 10 秒 (最大) の間の値のみが許可されます。設定した値が大きすぎると、再試行回数が減り、再試行による成功の可能性が低くなる可能性があります。

ゲートウェイ接続モード

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

非同期
同期

Java SDK V4 (Maven com.azure::azure-cosmos) 非同期 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();

Java SDK V4 (Maven com.azure::azure-cosmos) 同期 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);

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

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

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

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

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

次のステップ

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

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

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

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

次の方法で共有