共用方式為

優化 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 請求在使用 Azure Cosmos DB Java SDK v4 時是透過 TCP 進行的。 內部 Direct 模式採用特殊架構來動態管理網路資源，並獲得最佳效能。 直接模式下採用的用戶端架構，使網路利用率可預測，並能多工存取 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();

自訂直接連接模式

如果想要非預設的 Direct 模式行為，請建立一個 DirectConnectionConfig 實例並自訂其屬性，然後將自訂屬性實例傳給 Azure Cosmos DB 用戶端建構器的 directMode（） 方法。

這些設定控制了前面討論的底層直接模式架構的行為。

第一步，請使用以下建議的設定。 這些 DirectConnectionConfig 選項是進階設定，可能會以意想不到的方式影響 SDK 效能;我們建議用戶除非對權衡有信心且有必要，否則避免修改。 如果你在這個特定主題上遇到問題，請聯絡 Azure Cosmos 資料庫團隊 。

組態選項 預設 Recommended 詳細資訊
idleConnectionTimeout 「PT0」（零） 「PT0」（零） 這代表單一 連線 到端點/後端節點（代表複本）的閒置連線逾時時間。 預設情況下，SDK 不會自動關閉與後端節點的閒置連線。
idleEndpointTimeout 「PT1H」 「PT1H」 這代表端點/後端節點（代表複本）連線 池 的閒置連線逾時時間。 預設情況下，如果某個端點/後端節點沒有收到任何請求，SDK 會在 1 小時後關閉該端點/後端節點的連線池中所有連線，以節省網路資源和 I/O 成本。 對於稀疏或零星的流量模式，我們建議將此值設定為較高的數值，如 6 小時、12 小時甚至 24 小時，這樣 SDK 就不必頻繁開啟連線。 然而，這會消耗網路資源，且在任何時候會保持更多連線開啟。 若將此值設為零，則會停用閒置端點檢查。
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 總是 使用 Gateway 模式。 即使使用者已設定資料平面操作的直接模式，控制平面與元資料操作仍使用預設的閘道模式設定。 這對大多數使用者來說都很合適。 然而，想要使用直接模式進行資料平面操作並調整控制平面閘道模式參數的使用者，可以使用以下 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();

自訂閘道連接模式

若需要非預設的閘道模式行為，請建立 GatewayConnectionConfig 實例並自訂其屬性，然後將自訂屬性實例傳入 Azure Cosmos DB 用戶端建構器的 directMode（） 覆寫方法或 gatewayMode（） 方法。

第一步，請使用以下建議的設定。 這些 GatewayConnectionConfig 選項是進階設定，可能會以意想不到的方式影響 SDK 效能;我們建議用戶除非對權衡有信心且有必要，否則避免修改。 如果你在這個特定主題上遇到問題，請聯絡 Azure Cosmos 資料庫團隊 。

組態選項 預設 Recommended 詳細資訊
最大連接池大小 "1000" "1000" 這代表底層 HTTP 用戶端連線池大小的上限大小，也就是 SDK 為進入閘道模式請求所建立的最大連線數。 SDK 在向閘道發送請求時會重複使用這些連線。
idleConnectionTimeout 「PT60S」 「PT60S」 這代表單一 連線 到閘道器的閒置連線逾時時間。 過了這個時間，該連線將自動關閉並從連接池中移除。

後續步驟

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

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

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

  • Last updated on