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 der Anwendung für die Verwendung des integrierten Caches

Wenn Sie ein dediziertes Gateway bereitstellen, wird automatisch ein integrierter Cache erstellt. Sie müssen nicht alle Anwendungen, die Azure Cosmos DB verwenden, mit dem dedizierten Gateway verbinden, wenn sie den integrierten Cache nicht benötigen. Das Hinzufügen eines dedizierten Gateways wirkt sich nicht auf die vorhandenen Verbindungsmöglichkeiten mit Azure Cosmos DB aus. Beispielsweise können Sie einen CosmosClient im Gatewaymodus über den dedizierten Gatewayendpunkt verbinden, während ein anderer CosmosClient den direkten Modus verwendet.

Authentifizieren mit rollenbasierter Zugriffssteuerung

Das dedizierte Gateway verwendet dieselben Berechtigungen, Rollendefinitionen und Rollenzuweisungen wie Azure Cosmos DB. Wenn Sie bereits rollenbasierte Zugriffssteuerung (RBAC) für Datenebenenvorgänge in Ihrem Azure Cosmos DB-Konto konfiguriert haben, können Sie sie auch für die Authentifizierung für das dedizierte Gateway verwenden. Erfahren Sie mehr über RBAC für Azure Cosmos DB-Datenebenen Vorgängen.

Konfigurieren Sie Ihre CosmosClient, indem Sie den dedizierten Gatewayendpunkt, die Anmeldeinformationen und das Konfigurieren Gatewaykonnektivitätsmodusfestlegen. Alle dedizierten Gatewayendpunkte folgen demselben Muster. Entfernen Sie documents.azure.com vom ursprünglichen Endpunkt, und ersetzen Sie sie durch sqlx.cosmos.azure.com. Ein dediziertes Gateway verfügt immer über denselben Endpunkt, auch wenn Sie es entfernen und erneut bereitstellen.

.NET

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<dedicated-gateway-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential, new CosmosClientOptions { ConnectionMode = ConnectionMode.Gateway });

Wichtig

Der Direktverbindungsmodus ist die Standardeinstellung im .NET SDK. Sie müssen den Gatewaymodus explizit für die Verwendung des dedizierten Gateways konfigurieren.

Java

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<dedicated-gateway-endpoint>")
            .gatewayMode()
            .credential(credential);
            .buildClient();
    }
}

Wichtig

Der Direktverbindungsmodus ist die Standardeinstellung im Java SDK. Sie müssen den Gatewaymodus explizit für die Verwendung des dedizierten Gateways konfigurieren.

Node.js

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<dedicated-gateway-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential})

Python

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

Authentifizieren mit Verbindungszeichenfolgen

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.

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.

Wichtig

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.

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

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.39.0
Java SDK V4	>= 4.49.0
Node.js SDK	>= 4.1.0
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

    const queryRequestOptions = {
      bypassIntegratedCache: true };
    const querySpec = {
      query: "SELECT * from c"
    };
    const { resources: items, requestCharge: queryCharge } = await container.items
      .query(querySpec, queryRequestOptions)
      .fetchAll();

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