Konfigurieren des integrierten Azure Cosmos DB-Caches

GILT FÜR: NoSQL

In diesem Artikel wird beschrieben, wie Sie ein dediziertes Gateway bereitstellen, den integrierten Cache konfigurieren und eine Verbindung mit Ihrer Anwendung herstellen.

Voraussetzungen

• Wenn Sie kein Azure-Abonnement besitzen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
• Eine vorhandene Anwendung, die Azure Cosmos DB nutzt. Wenn Sie noch keine haben, finden Sie hier einige Beispiele.
• Ein vorhandenes Azure Cosmos DB-API für NoSQL-Konto.

Bereitstellen des dedizierten Gateways

1. Navigieren Sie im Azure-Portal zu einem Azure Cosmos DB-Konto, und wählen Sie die Registerkarte Dediziertes Gateway aus.

   

2. Füllen Sie das Formular Dediziertes Gateway mit den folgenden Details aus:

   • Dediziertes Gateway: Aktivieren Sie den Umschalter Bereitgestellt.
   • SKU: Wählen Sie eine SKU mit der benötigten Compute- und Arbeitsspeichergröße aus. Der integrierte Cache verwendet etwa 50 % des Arbeitsspeichers, und der verbleibende Speicher wird für Metadaten und Routinganforderungen an die Back-End-Partitionen verwendet.
   • Anzahl von Instanzen: Anzahl der Knoten. Für die Entwicklung wird zu Beginn ein Knoten der Größe D4 empfohlen. Basierend auf der Datenmenge, die Sie zwischenspeichern müssen, und zum Erzielen von Hochverfügbarkeit können Sie die Knotengröße nach den ersten Tests erhöhen.

   

3. Wählen Sie Speichern aus, und warten Sie ca. 5 bis 10 Minuten, bis die Bereitstellung des dedizierten Gateways abgeschlossen ist. Nach Abschluss der Bereitstellung wird die folgende Benachrichtigung angezeigt:

   

Konfigurieren des integrierten Caches

Wenn Sie ein dediziertes Gateway erstellen, wird automatisch auch integrierter Cache bereitgestellt.

1. Ändern Sie die Verbindungszeichenfolge Ihrer Anwendung, damit sie den neuen dedizierten Gatewayendpunkt verwendet.

   Sie finden die aktualisierte Verbindungszeichenfolge des dedizierten Gateways auf dem Blatt Schlüssel:

   

   Alle Verbindungszeichenfolgen für dedizierte Gateways folgen dem gleichen Muster. Entfernen Sie documents.azure.com aus der ursprünglichen Verbindungszeichenfolge, und ersetzen Sie sie durch sqlx.cosmos.azure.com. Ein dediziertes Gateway hat immer dieselbe Verbindungszeichenfolge, selbst wenn Sie es entfernen und neu bereitstellen.

   Sie müssen die Verbindungszeichenfolge in Anwendungen, die dasselbe Azure Cosmos DB-Konto verwenden, nicht ändern. Beispielsweise können Sie einen CosmosClient im Gatewaymodus über den dedizierten Gatewayendpunkt verbinden, während ein anderer CosmosClient den direkten Modus verwendet. Anders ausgedrückt: Das Hinzufügen eines dedizierten Gateways wirkt sich nicht auf die vorhandenen Verbindungsmöglichkeiten mit Azure Cosmos DB aus.

2. Wenn Sie das .NET oder Java SDK verwenden, legen Sie als Verbindungsmodus den Gatewaymodus fest. Dieser Schritt ist für die Python und Node.js SDKs nicht erforderlich, da sie neben dem Gatewaymodus keine weiteren Optionen zum Herstellen von Verbindungen bieten.

Hinweis

Wenn Sie die neueste .NET- oder Java SDK-Version verwenden, ist der Standardverbindungsmodus der direkte Modus. Um den integrierten Cache zu verwenden, müssen Sie diesen Standardwert überschreiben.

Anpassen der Anforderungskonsistenz

Sie müssen sicherstellen,dass die Anforderungskonsistenz auf „Sitzungskonsistenz“ oder „Letztliche Konsistenz“ festgelegt ist. Andernfalls wird der integrierte Cache immer von der Anforderung umgangen. Die einfachste Vorgehensweise zum Konfigurieren der spezifischen Konsistenz für alle Lesevorgänge besteht darin, diese auf Kontoebene festzulegen. Sie können die Konsistenz auch auf Anforderungsebene konfigurieren. Dies wird empfohlen, wenn der integrierte Cache nur von einem Teil Ihrer Lesezugriffe verwendet werden soll.

Hinweis

Wenn Sie das Python SDK verwenden, müssen Sie die Konsistenzebene für jede Anforderung explizit festlegen. Die Standardeinstellung auf Kontoebene wird nicht automatisch angewandt.

Anpassen von MaxIntegratedCacheStaleness

Legen Sie MaxIntegratedCacheStaleness als maximale Dauer der Beibehaltung alter Cachedaten fest. Es wird empfohlen, MaxIntegratedCacheStaleness so hoch wie möglich einzustellen, da dies die Wahrscheinlichkeit von Cachetreffern für wiederholte Punktlesevorgänge und Abfragen erhöht. Wenn Sie MaxIntegratedCacheStaleness auf 0 setzen, verwendet Ihre Leseanforderung unabhängig von der Konsistenzebene niemals den integrierten Cache. Die Voreinstellung für MaxIntegratedCacheStaleness beträgt 5 Minuten.

Hinweis

MaxIntegratedCacheStaleness auf bis zu 10 Jahre festgelegt werden. In der Praxis ist dieser Wert die maximale Überalterung, und der Cache kann aufgrund von etwaiger aufgetretener Knotenneustarts auf einen früheren Zeitpunkt zurückgesetzt werden.

Das Anpassen von MaxIntegratedCacheStaleness wird in diesen Versionen der einzelnen SDKs unterstützt:

SDK	Unterstützte Versionen
.NET SDK v3	>= 3.30.0
Java SDK V4	>= 4.34.0
Node.js SDK	>=3.17.0
Python SDK	>=4.3.1

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(30) 
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setMaxIntegratedCacheStaleness(Duration.ofMinutes(30));
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

 const queryRequestOptions = {
   maxIntegratedCacheStalenessInMs: 1800000 };
 const querySpec = {
   query: "SELECT * from c"
 };
 const { resources: items } = await container.items
   .query(querySpec, queryRequestOptions)
   .fetchAll();

Python

query = "SELECT * FROM c"
container.query_items(
    query=query,
    max_integrated_cache_staleness_in_ms=1800000
)

Umgehung des integrierten Caches (Vorschau)

Verwenden Sie die Anforderungsoption BypassIntegratedCache, um zu steuern, welche Anforderungen den integrierten Cache verwenden. Schreibvorgänge, Punktlesevorgänge und Abfragen, die den integrierten Cache umgehen, verwenden keinen Cachespeicher und sparen so Platz für andere Elemente. Anforderungen, die den Cache umgehen, werden trotzdem über das dedizierte Gateway weitergeleitet. Diese Anforderungen werden vom Back-End bedient und kosten RUs.

Das Umgehen des Cache wird in folgenden Versionen der einzelnen SDKs unterstützt:

SDK	Unterstützte Versionen
.NET SDK v3	>= 3.35.0-preview
Java SDK V4	>= 4.49.0
Node.js SDK	Nicht unterstützt
Python SDK	Nicht unterstützt

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setIntegratedCacheBypassed(true);
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

Die Anforderungsoption zur Umgehung des integrierten Cache ist im Node.js-SDK nicht verfügbar.

Python

Die Anforderungsoption zur Umgehung des integrierten Cache ist im Python-SDK nicht verfügbar.

Überprüfen von Cachetreffern

Zum Abschluss starten Sie Ihre Anwendung neu und führen eine Überprüfung auf Treffer im integrierten Cache für wiederholte Punktlesevorgänge oder Abfragen durch, indem Sie prüfen, ob die Anforderungsgebühr bei 0 liegt. Nachdem Sie Ihren CosmosClient so geändert haben, dass er den dedizierten Gatewayendpunkt verwendet, werden alle Anforderungen über das dedizierte Gateway weitergeleitet.

Damit eine Leseanforderung (Punktlesevorgang oder Abfrage) den integrierten Cache verwendet, müssen alle der folgenden Kriterien erfüllt sein:

• Ihr Client stellt eine Verbindung mit dem dedizierten Gatewayendpunkt her.
• Ihr Client verwendet den Gatewaymodus (beim Python und Node.js SDK wird immer der Gatewaymodus verwendet).
• Die Konsistenz für die Anforderung muss auf „Letztliche Konsistenz“ festgelegt sein.

Hinweis

Möchten Sie Feedback zum integrierten Cache äußern? Teilen Sie uns Ihre Meinung mit! Sie können Feedback direkt an das Azure Cosmos DB-Entwicklungsteam senden: cosmoscachefeedback@microsoft.com

Nächste Schritte

• Häufig gestellte Fragen zum integrierten Cache
• Übersicht über den integrierten Cache
• Dediziertes Gateway