Important
Java SDK 中的吞吐量控制 API 會標註@Beta並可能變更。 升級前請先檢視 SDK 變更記錄 以取得更新。
吞吐量控制群組允許您限制 Azure Cosmos DB 作業的請求單元(RU)消耗。 當您有多個應用程式或工作負載共用同一容器,且希望確保單一工作負載不會耗盡所有可用吞吐量時,這很有用。 吞吐量控制功能可於 Azure Cosmos DB Java SDK v4 從 4.13.0 版本開始使用。
Java SDK 支援三種吞吐量控制模式:
- 本地吞吐量控制 - 限制單一用戶端實例內的 RU 消耗。
- 全域吞吐量控制 ——透過中繼資料容器協調多個用戶端實例,限制 RU 消耗。
- 伺服器端吞吐量控制 - 利用伺服器端吞吐量桶限制 RU 消耗。
Prerequisites
- Azure Cosmos DB Java SDK v4 >= 4.13.0(用於本地與全域吞吐量控制)
- Azure Cosmos DB Java SDK v4 >= 4.54.0(用於使用 Change Feed 處理器進行吞吐量控制)
- Azure Cosmos DB Java SDK v4 >= 4.83.0(用於伺服器端吞吐量控制,使用吞吐量桶)
必要匯入
本文中的程式碼範例使用以下匯入方式:
import com.azure.cosmos.CosmosAsyncClient;
import com.azure.cosmos.CosmosAsyncContainer;
import com.azure.cosmos.CosmosAsyncDatabase;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.GlobalThroughputControlConfig;
import com.azure.cosmos.ThroughputControlGroupConfig;
import com.azure.cosmos.ThroughputControlGroupConfigBuilder;
import com.azure.cosmos.models.CosmosItemRequestOptions;
import com.azure.cosmos.models.PartitionKey;
import com.azure.cosmos.models.ChangeFeedProcessor;
import com.azure.cosmos.models.ChangeFeedProcessorBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.fasterxml.jackson.databind.JsonNode;
import java.time.Duration;
建立吞吐量控制群組
使用 ThroughputControlGroupConfigBuilder 建立吞吐量控制群組設定。 您可以設定:
Note
建立吞吐量控制群組時,您必須設定至少其中一個 targetThroughput、 targetThroughputThreshold、 priorityLevel或 throughputBucket 。 若要控制本地與全域吞吐量,請設定 targetThroughput 或 targetThroughputThreshold。 若要進行伺服器端吞吐量控制,請設定 priorityLevel 或 throughputBucket(或兩者皆設)。
本地吞吐量控制
本地吞吐量控制限制單一實例內 CosmosAsyncClient 的 RU 消耗。 當您想在同一應用程式中隔離不同類型的操作時,這非常有用。
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("localControlGroup")
.targetThroughputThreshold(0.1) // limit to 10% of provisioned throughput
.build();
container.enableLocalThroughputControlGroup(groupConfig);
啟用本地吞吐量控制後,在此用戶端實例中,該容器上的所有操作都將受限於已設定的 RU/s。
多個本地控制群組
您可以在同一容器上建立多個本機控制群組。 例如,要分開讀取與寫入工作負載:
// Limit reads to 25% of provisioned throughput
ThroughputControlGroupConfig readGroup =
new ThroughputControlGroupConfigBuilder()
.groupName("reads")
.targetThroughputThreshold(0.25)
.defaultControlGroup(true) // default group for all requests
.build();
container.enableLocalThroughputControlGroup(readGroup);
// Limit writes to a fixed 500 RU/s
ThroughputControlGroupConfig writeGroup =
new ThroughputControlGroupConfigBuilder()
.groupName("writes")
.targetThroughput(500)
.build();
container.enableLocalThroughputControlGroup(writeGroup);
若要將特定操作指派給非預設群組,請使用 CosmosItemRequestOptions:
CosmosItemRequestOptions requestOptions = new CosmosItemRequestOptions();
requestOptions.setThroughputControlGroupName("writes");
container.createItem(newItem, new PartitionKey(newItem.getPartitionKey()), requestOptions)
.block();
全域吞吐量控制
全域吞吐量控制透過在 Azure Cosmos DB 中使用共用的中繼資料容器,協調多個用戶端實例之間的 RU 消耗。 當您有多個微服務或應用程式實例存取同一容器,並希望強制執行集體吞吐量限制時,這非常有用。
設定控制容器
全域吞吐量控制功能需要一個元資料容器來追蹤跨用戶端的 RU 使用情況。 您可以為此目的建立專用資料庫與容器,或使用現有容器。
// Create a dedicated database and container for throughput control metadata
client.createDatabaseIfNotExists("ThroughputControlDatabase").block();
CosmosAsyncDatabase throughputControlDatabase =
client.getDatabase("ThroughputControlDatabase");
throughputControlDatabase
.createContainerIfNotExists("ThroughputControlContainer", "/groupId")
.block();
啟用全域吞吐量控制
// Create the throughput control group config
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("globalControlGroup")
.targetThroughputThreshold(0.25) // limit to 25% of provisioned throughput
.defaultControlGroup(true)
.build();
// Create the global control config pointing to the metadata container
GlobalThroughputControlConfig globalControlConfig =
client.createGlobalThroughputControlConfigBuilder(
"ThroughputControlDatabase",
"ThroughputControlContainer")
.setControlItemRenewInterval(Duration.ofSeconds(5))
.setControlItemExpireInterval(Duration.ofSeconds(11))
.build();
// Enable global throughput control on the target container
container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);
全域吞吐量控制的配置選項
| Property | Description | Default |
|---|---|---|
controlItemRenewInterval |
每個用戶端更新其中繼資料容器中的使用情況的頻率(至少 5 秒)。 | 5 秒 |
controlItemExpireInterval |
離線用戶端被偵測的速度以及其份額重新分配的速度。 必須是 > 2 次× renewInterval + 1。 | 11 秒 |
Important
controlItemExpireInterval 必須大於 2 × controlItemRenewInterval + 1 秒。 使用較短的間隔能讓系統反應更快,但同時增加元資料負擔。
伺服器端吞吐量控制
伺服器端吞吐量控制使用 吞吐量桶 在伺服器層級強制執行 RU 限制。 若要支援吞吐量桶,請使用 Azure Cosmos DB Java SDK v4 版本 4.83.0 或更新版本。
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("serverSideControlGroup")
.throughputBucket(2) // assign to server-side bucket 2
.build();
container.enableServerThroughputControlGroup(groupConfig);
Note
伺服器端吞吐量控制需要在吞吐量控制群組設定中設定 priorityLevel 或 throughputBucket,或同時設定兩者。
有關吞吐量桶的更多資訊,請參閱 Azure Cosmos DB 中的吞吐量桶。
錯誤處理
當請求超過其控制群組分配的 RU 預算時,SDK 會在本機拒絕該請求,並回傳 CosmosException with 狀態 429 (Too Many Requests),且不會將請求送交服務。 應用程式必須照常處理 429 個回應(SDK 內建的重試政策適用)。
若要順利處理初始化錯誤,請設定 continueOnInitError 為 true:
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("resilientGroup")
.targetThroughputThreshold(0.5)
.continueOnInitError(true) // fall back to full throughput on init failure
.build();
使用 Change Feed Processor 進行輸送量控制
您可以對 變更摘要處理器 套用吞吐量控制,以限制變更摘要處理期間的 RU 消耗。 這在回填情境中特別有用,因為變更資料串流處理器會讀取大量資料。 此整合需要 Azure Cosmos DB Java SDK v4 4.54.0 版或更新版本。
若要在變更饋源處理器上啟用吞吐量控制,請在建置處理器前先在饋源容器上設定吞吐量控制群組:
// Configure throughput control on the feed container
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("cfpControlGroup")
.targetThroughputThreshold(0.3) // limit to 30% of provisioned throughput
.defaultControlGroup(true)
.build();
feedContainer.enableLocalThroughputControlGroup(groupConfig);
// Build the Change Feed Processor — it inherits the throughput control settings
ChangeFeedProcessor changeFeedProcessor = new ChangeFeedProcessorBuilder()
.hostName("host-1")
.feedContainer(feedContainer)
.leaseContainer(leaseContainer)
.handleChanges(docs -> {
for (JsonNode doc : docs) {
// process each change
}
})
.buildChangeFeedProcessor();
您也可以在 Change Feed 處理器中使用全域吞吐量控制,以協調多個處理器實例之間的 RU 限制。