Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Important
Die Durchsatzsteuerelement-APIs im Java SDK sind mit @Beta annotiert und können geändert werden. Überprüfen Sie das SDK-Änderungsprotokoll auf Updates vor dem Upgrade.
Mithilfe von Durchsatzsteuerungsgruppen können Sie den Anforderungseinheitsverbrauch (RU) Ihrer Azure Cosmos DB Vorgänge einschränken. Dies ist nützlich, wenn Sie mehrere Anwendungen oder Workloads gemeinsam mit demselben Container haben und sicherstellen möchten, dass eine Workload nicht den gesamten verfügbaren Durchsatz belegt. Das Durchsatzsteuerelement ist ab Version 4.13.0 im Azure Cosmos DB Java SDK v4 verfügbar.
Das Java SDK unterstützt drei Durchsatzsteuerungsmodi:
- Lokale Durchsatzsteuerung – Beschränkt den RU-Verbrauch innerhalb einer einzelnen Clientinstanz.
- Globale Durchsatzsteuerung – Beschränkt den RU-Verbrauch über mehrere Clientinstanzen hinweg durch Koordination über einen Metadatencontainer.
- Serverseitige Durchsatzsteuerung – Beschränkt den RU-Verbrauch mithilfe von serverseitigen Durchsatz-Buckets.
Prerequisites
- Azure Cosmos DB Java SDK v4 = 4.13.0 >(für lokale und globale Durchsatzsteuerung)
- Azure Cosmos DB Java SDK v4 >= 4.54.0 (für Durchsatzsteuerung mit Änderungsfeedprozessor)
- Azure Cosmos DB Java SDK v4 = 4.83.0 >(für serverseitige Durchsatzsteuerung mit Durchsatz-Buckets)
Erforderliche Importe
Die Codebeispiele in diesem Artikel verwenden die folgenden Importe:
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;
Erstellen Sie eine Durchsatzsteuerungsgruppe
Verwenden Sie die ThroughputControlGroupConfigBuilder Methode, um eine Konfiguration einer Durchsatzsteuerungsgruppe zu erstellen. Sie können festlegen:
| Eigenschaft | Description |
|---|---|
groupName |
Ein eindeutiger Name für die Steuerelementgruppe. |
targetThroughput |
Ein absoluter RU/s-Grenzwert für die Gruppe (muss > 0 sein). |
targetThroughputThreshold |
Ein Prozentsatz (0, 1] des gesamten bereitgestellten Durchsatzes, der dieser Gruppe zugeordnet werden soll. |
defaultControlGroup |
Gibt an, ob dies die Standardgruppe für alle Anfragen ist, die keiner bestimmten Gruppe zugewiesen sind. |
priorityLevel |
Die Prioritätsebene (PriorityLevel.HIGH oder PriorityLevel.LOW) für die prioritätsbasierte Ausführung. |
throughputBucket |
Die serverseitige Durchsatz-Bucket-ID (>= 0), die dieser Gruppe zugewiesen werden soll. Wird mit serverseitigem Durchsatzsteuerelement verwendet. |
continueOnInitError |
Wenn true werden Vorgänge auf den vollständigen Durchsatz des Containers zurückgreifen, wenn die Steuerungsgruppe nicht initialisiert werden kann. |
Note
Sie müssen mindestens eine von targetThroughput, targetThroughputThreshold, , priorityLeveloder throughputBucket beim Erstellen einer Durchsatzsteuerungsgruppe festlegen. Legen Sie für lokale und globale Durchsatzsteuerung fest targetThroughput oder targetThroughputThreshold. Legen Sie für die serverseitige Durchsatzsteuerung priorityLevel oder throughputBucket fest (oder beide).
Lokale Durchsatzsteuerung
Die Steuerung des lokalen Durchsatzes begrenzt den RU-Verbrauch innerhalb einer einzelnen CosmosAsyncClient Instanz. Dies ist nützlich, wenn Sie verschiedene Arten von Vorgängen innerhalb derselben Anwendung isolieren möchten.
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("localControlGroup")
.targetThroughputThreshold(0.1) // limit to 10% of provisioned throughput
.build();
container.enableLocalThroughputControlGroup(groupConfig);
Nach dem Aktivieren der lokalen Durchsatzsteuerung sind alle Vorgänge für diesen Container auf die konfigurierten RU/s innerhalb dieser Clientinstanz beschränkt.
Mehrere lokale Kontrollgruppen
Sie können mehrere lokale Kontrollgruppen im selben Container erstellen. Beispiel: Zum Trennen von Lese- und Schreibarbeitslasten:
// 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);
Um einer nicht standardmäßigen Gruppe einen bestimmten Vorgang zuzuweisen, verwenden Sie Folgendes CosmosItemRequestOptions:
CosmosItemRequestOptions requestOptions = new CosmosItemRequestOptions();
requestOptions.setThroughputControlGroupName("writes");
container.createItem(newItem, new PartitionKey(newItem.getPartitionKey()), requestOptions)
.block();
Globale Durchsatzsteuerung
Das globale Durchsatzsteuerelement koordiniert den RU-Verbrauch über mehrere Clientinstanzen hinweg, indem ein freigegebener Metadatencontainer in Azure Cosmos DB verwendet wird. Dies ist nützlich, wenn Sie über mehrere Microservices oder Anwendungsinstanzen verfügen, die auf denselben Container zugreifen und einen kollektiven Durchsatzgrenzwert erzwingen möchten.
Steuercontainer einrichten
Für das Feature für die globale Durchsatzsteuerung ist ein Metadatencontainer erforderlich, um die RU-Nutzung für alle Clients nachzuverfolgen. Sie können zu diesem Zweck eine dedizierte Datenbank und einen dedizierten Container erstellen oder einen vorhandenen Container verwenden.
// Create a dedicated database and container for throughput control metadata
client.createDatabaseIfNotExists("ThroughputControlDatabase").block();
CosmosAsyncDatabase throughputControlDatabase =
client.getDatabase("ThroughputControlDatabase");
throughputControlDatabase
.createContainerIfNotExists("ThroughputControlContainer", "/groupId")
.block();
Globale Durchsatzsteuerung aktivieren
// 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);
Konfigurationsoptionen für die globale Durchsatzsteuerung
| Eigenschaft | Description | Default |
|---|---|---|
controlItemRenewInterval |
Wie oft (mindestens 5 Sekunden) aktualisiert jeder Client seine Verwendung im Metadatencontainer. | 5 Sekunden |
controlItemExpireInterval |
Wie schnell Offlineclients erkannt werden und wie schnell ihr Anteil weiterverteilt wird. Muss > 2 × renewInterval + 1 sein. | 11 Sekunden |
Important
Der controlItemExpireInterval Wert muss größer als 2 × controlItemRenewInterval + 1 Sekunde sein. Die Verwendung kürzerer Intervalle macht das System reaktionsfähiger, erhöht jedoch den Metadatenaufwand.
Serverseitige Durchsatzsteuerung
Die serverseitige Durchsatzsteuerung verwendet Durchsatz-Buckets, um RU-Grenzwerte auf Serverebene zu erzwingen. Verwenden Sie für die Unterstützung des Durchsatz-Buckets Azure Cosmos DB Java SDK v4, Version 4.83.0 oder höher.
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("serverSideControlGroup")
.throughputBucket(2) // assign to server-side bucket 2
.build();
container.enableServerThroughputControlGroup(groupConfig);
Note
Für die serverseitige Durchsatzsteuerung muss entweder priorityLevel oder throughputBucket (oder beide) in der Konfiguration der Durchsatzsteuerungsgruppe festgelegt werden.
Weitere Informationen zu Durchsatz-Buckets finden Sie unter Durchsatz-Buckets in Azure Cosmos DB.
Fehlerbehandlung
Wenn eine Anforderung das zugewiesene RU-Budget für ihre Kontrollgruppe überschreitet, lehnt das SDK es lokal ab und gibt einen CosmosException Status 429 (Too Many Requests)zurück, ohne die Anforderung an den Dienst zu senden. Anwendungen müssen weiterhin 429 Antworten wie gewohnt verarbeiten (die integrierte Wiederholungsrichtlinie des SDK gilt).
Um Initialisierungsfehler ordnungsgemäß zu behandeln, legen Sie continueOnInitError auf true fest:
ThroughputControlGroupConfig groupConfig =
new ThroughputControlGroupConfigBuilder()
.groupName("resilientGroup")
.targetThroughputThreshold(0.5)
.continueOnInitError(true) // fall back to full throughput on init failure
.build();
Durchsatzsteuerung mit Change Feed Processor
Sie können die Durchsatzsteuerung auf den Change Feed Processor anwenden, um den RU-Verbrauch während der Änderungsfeedverarbeitung zu begrenzen. Dies ist besonders hilfreich bei Backfill-Szenarien, in denen der Änderungsfeedprozessor große Datenmengen liest. Für diese Integration ist Azure Cosmos DB Java SDK v4, Version 4.54.0 oder höher, erforderlich.
Um die Durchsatzsteuerung für den Änderungsfeedprozessor zu aktivieren, konfigurieren Sie eine Durchsatzsteuerungsgruppe im Feedcontainer, bevor Sie den Prozessor erstellen:
// 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();
Sie können auch die globale Durchsatzsteuerung mit dem Change Feed Processor verwenden, um RU-Grenzwerte für mehrere Prozessorinstanzen zu koordinieren.