共用方式為

調整 Azure Cosmos DB JAVA SDK v4 的連線設定

  • 發行項

適用於：NoSQL

重要

本文提供的效能秘訣僅適用於 Azure Cosmos DB JAVA SDK v4。 如需更多資訊，請參閱 Azure Cosmos DB Java SDK v4 版本資訊、Maven 存放庫和 Azure Cosmos DB Java SDK v4 疑難排解指南。 如果您目前使用的版本比 v4 舊，請參閱遷移至 Azure Cosmos DB Java SDK v4 指南，以取得升級至 v4 的協助。

Azure Cosmos DB 是一個既快速又彈性的分散式資料庫，可在獲得延遲與輸送量保證的情況下順暢地調整。 使用 Azure Cosmos DB 時，您不須進行主要的架構變更，或是撰寫複雜的程式碼來調整您的資料庫。 相應增加和減少就像進行單一 API 呼叫或 SDK 方法呼叫一樣簡單。 不過，由於 Azure Cosmos DB 是透過網路呼叫存取，所以您可以在使用 Azure Cosmos DB Java SDK v4 時，調整連線以達到最高效能。

連線設定

注意

在 Azure Cosmos DB JAVA SDK v4 中，直接模式最適合用來改善工作負載最大的資料庫效能。

若要深入了解不同的連線選項，請參閱連線模式一文。

直接連接模式

Java SDK 預設連線模式是直接。 使用 Azure Cosmos DB JAVA SDK v4 時，會透過 TCP 提出直接模式 Cosmos DB 要求。 直接模式會在內部使用特殊的架構來動態管理網路資源，並達到最佳效能。 直接模式中採用的用戶端架構，能讓網路使用率得以預測，並實現對 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();

自訂直接連接模式

如果需要非預設的直接模式行為，請建立 DirectConnectionConfig 執行個體，並自訂其屬性，然後將自訂的屬性執行個體傳遞至 Azure Cosmos DB 用戶端建立器中的 directMode() 方法。

這些組態設定會控制上述基礎直接模式架構的行為。

首先，請使用下列建議的組態設定。 這些 DirectConnectionConfig 選項屬於進階設定，可能會以非預期的方式影響 SDK 效能；建議使用者避免修改這類選項，除非確實了解修改的優缺點，而且真的必須修改。 如果遇到關於此特定主題的問題，請連絡 Azure Cosmos DB 小組。

組態選項 預設 建議需求 詳細資料
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) 這代表端點/後端節點 (代表複本) 的單一連線的閒置連線逾時持續時間。 根據預設，SDK 不會自動關閉後端節點的閒置連線。
idleEndpointTimeout "PT1H" "PT1H" 這代表端點/後端節點 (代表複本) 的連線集區的閒置連線逾時持續時間。 根據預設，如果特定端點/後端節點沒有傳入要求，SDK 會在 1 小時後關閉連線集區中連至該端點/後端節點的所有連線，以節省網路資源和 I/O 成本。 針對疏鬆或偶爾的流量模式，我們建議將此值設定為較高的數值，例如 6 小時、12 小時甚至 24 小時，讓 SDK 不需要經常開啟連線。 不過這會用到網路資源，而且在任何時候都會保持較高的開啟連線數。 如果此值設為 ZERO，便會停用閒置端點檢查。
maxConnectionsPerEndpoint "130" "130" 這代表端點/後端節點 (代表複本) 之連接集區的大小上限。 SDK 會根據傳入的同時要求，依需求建立端點/後端節點的連線。 根據預設，如有需要，SDK 可為連線建立最多 130 個端點/後端節點。 (注意：SDK 不會預先建立這 130 個連線)。
maxRequestsPerConnection "30" "30" 這代表在特定端點/後端節點 (代表複本) 的單一連線上可排入佇列的要求數上限。 SDK 會根據傳入的同時要求，依需求將端點/後端節點的單一連線要求排入佇列。 根據預設，如有需要，SDK 可將特定端點/後端節點單一連線的最多 30 個要求排入佇列。 (注意：SDK 不會預先將單一連線的這 30 個要求排入佇列)。
connectTimeout "PT5S" "~PT1S" 這代表與端點/後端節點建立單一連線的連線建立逾時持續時間。 根據預設，SDK 會等待最多 5 秒進行連線建立，才會擲回錯誤。 TCP 連線建立會使用多步驟交握來增加連線建立時間的延遲，因此，建議客戶根據自己的網路頻寬和環境設定來設定此值。 注意：這個 ~PT1S 建議僅適用於部署在其 Cosmos DB 帳戶共置區域的應用程式。
networkRequestTimeout "PT5S" "PT5S" 這代表單一要求的網路逾時持續時間。 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();

自訂閘道連線模式

如果需要非預設的閘道模式行為，請建立 DirectConnectionConfig 執行個體，並自訂其屬性，然後將自訂的屬性執行個體傳遞至 Azure Cosmos DB 用戶端建立器中的上述 directMode() 覆寫方法或 gatewayMode() 方法。

首先，請使用下列建議的組態設定。 這些 GatewayConnectionConfig 選項屬於進階設定，可能會以非預期的方式影響 SDK 效能；建議使用者避免修改這類選項，除非確實了解修改的優缺點，而且真的必須修改。 如果遇到關於此特定主題的問題，請連絡 Azure Cosmos DB 小組。

組態選項 預設 建議需求 詳細資料
maxConnectionPoolSize "1000" "1000" 這代表基礎 HTTP 用戶端連線集區大小的上限，這是 SDK 針對進入閘道模式的要求建立的最大連線數。 SDK 會在將要求傳送至閘道時重複使用這些連線。
idleConnectionTimeout "PT60S" "PT60S" 這代表閘道單一連線的閒置連線逾時持續時間。 此時間過後，連線會自動關閉，並從連線集區中移除。

下一步

若要深入了解 Java SDK 的效能秘訣，請參閱 Azure Cosmos DB Java SDK 第 4 版的效能秘訣。

若要深入了解如何針對規模和高效能設計您的應用程式，請參閱 Azure Cosmos DB 的資料分割與調整規模。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？ 您可以使用現有資料庫叢集的相關資訊進行容量規劃。