Azure Cosmos DB Java SDK v4 中的吞吐量控制群組

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 建立吞吐量控制群組設定。 您可以設定:

Property Description
groupName 控制群組的唯一名稱。
targetThroughput 群組的絕對 RU/s 限制(必須 > 0)。
targetThroughputThreshold 分配給此群組的總配置吞吐量百分比(0,1]。
defaultControlGroup 是否為所有未指派至特定群組的請求的預設群組。
priorityLevel PriorityLevel.LOW的優先權等級( 或 PriorityLevel.HIGH)。
throughputBucket 要指派給此群組的伺服器端吞吐量桶 ID>(= 0)。 與伺服器端吞吐量控制搭配使用。
continueOnInitError 如果 true,當控制群組無法初始化時,作業會退回使用容器的完整吞吐量。

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 限制。