Aktivieren des integrierten Caches

Abgeschlossen

Aktivieren des integrierten Caches

Die Aktivierung des integrierten Caches umfasst im Wesentlichen zwei Schritte:

• Erstellen eines dedizierten Gateways in Ihrem Azure Cosmos DB for NoSQL-Konto
• Aktualisieren Ihres SDK-Codes für die Verwendung des Gateways für Anforderungen

Erstellen eines dedizierten Gateways

Als Erstes müssen Sie ein dediziertes Gateway in Ihrem Konto bereitstellen. Hierzu können Sie das Portal und den Bereich Dedicated Gateway (Dediziertes Gateway) verwenden.

Im Rahmen des Bereitstellungsprozesses werden Sie aufgefordert, die Anzahl von Gatewayinstanzen und eine SKU zu konfigurieren. Diese Einstellungen bestimmen die Anzahl von Knoten sowie die Computeressourcen und die Arbeitsspeichergröße für die einzelnen Gatewayknoten. Die Anzahl von Knoten und die SKU können später geändert werden, wenn sich die Menge der zwischenzuspeichernden Daten erhöht.

Nachdem das neue Gateway bereitgestellt wurde, können Sie den Endpunkt für das Gateway abrufen.

Hinweis

Der Gatewayendpunkt unterscheidet sich vom typischen Endpunkt, der mit einem Azure Cosmos DB for NoSQL-Client verwendet wird.

Aktualisieren des .NET SDK-Codes

Damit der .NET SDK-Client den integrierten Cache verwenden kann, müssen drei Voraussetzungen erfüllt sein:

• Der Client verwendet den dedizierten Gatewayendpunkt anstelle des typischen Endpunkts.
• Der Client ist für die Verwendung des Modus Gateway (anstelle des standardmäßigen Verbindungsmodus Direkt) konfiguriert.
• Die Konsistenzebene des Clients muss auf Sitzung oder Letztliche Konsistenz festgelegt sein.

Stellen Sie zunächst sicher, dass der Endpunkt auf den Endpunkt des dedizierten Gateways festgelegt ist. In der Regel befinden sich Azure Cosmos DB for NoSQL-Endpunkte im Format „<cosmos-account-name>.documents.azure.com“. Für das dedizierte Gateway befindet sich der Endpunkt in der Struktur „<cosmos-account-name>.sqlx.cosmos.azure.com“.

Anstatt einen Kontoschlüssel zu verwenden, konfigurieren Sie das SDK so, dass eine verwaltete Identität für die Authentifizierung verwendet wird. Der aktualisierte Code folgt.

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

string endpoint = "https://<cosmos-account-name>.sqlx.cosmos.azure.com/";

CosmosClientOptions options = new()
{
    ConnectionMode = ConnectionMode.Gateway,
    ConsistencyLevel = ConsistencyLevel.Session // or ConsistencyLevel.Eventual
};

// Use DefaultAzureCredential to authenticate with managed identity.
CosmosClient client = new(endpoint, new DefaultAzureCredential(), options);

Hinweis

Stellen Sie sicher, dass Ihre Anwendung eine verwaltete Identität aktiviert hat und der verwalteten Identität die Rolle Integrierter Cosmos DB-Mitwirkender für Daten im Azure Cosmos DB-Konto gewährt wurde.

Konfigurieren von Punktlesevorgängen

Wenn Sie einen Punktlesevorgang für die Verwendung des integrierten Caches konfigurieren möchten, müssen Sie ein Objekt vom Typ ItemRequestOptions erstellen. In diesem Objekt können Sie die Eigenschaft ConsistencyLevel manuell auf ConsistencyLevel.Session oder ConsistencyLevel.Eventual festlegen. Anschließend können Sie die Optionenvariable im Aufruf der Methode ReadItemAsync verwenden.

string id = "9DB28F2B-ADC8-40A2-A677-B0AAFC32CAC8";
PartitionKey partitionKey = new("56400CF3-446D-4C3F-B9B2-68286DA3BB99");

ItemRequestOptions requestOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Session
};

ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey, requestOptions: requestOptions);

Verwenden Sie zur Beobachtung der RU-Nutzung die Eigenschaft RequestCharge der Antwortvariablen. Beim ersten Aufruf dieses Lesevorgang wird die erwartete Anzahl von Anforderungseinheiten verwendet. In diesem Beispiel wäre dies eine einzelne RU für einen Punktlesevorgang. Bei nachfolgenden Anforderungen werden keine Anforderungseinheiten verwendet, da die Daten bis zu ihrem Ablauf aus dem Cache abgerufen werden.

Console.WriteLine($"Request charge:\t{response.RequestCharge:0.00} RU/s");

Konfigurieren von Abfragen

Wenn Sie eine Abfrage für die Verwendung des integrierten Caches konfigurieren möchten, erstellen Sie ein Objekt vom Typ QueryRequestOptions. In diesem Objekt müssen Sie auch die Konsistenzebene manuell ändern. Übergeben Sie dann die Optionenvariable an den Aufruf der Methode GetItemQueryIterator.

string sql = "SELECT * FROM products";
QueryDefinition query = new(sql);

QueryRequestOptions queryOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Eventual
};

FeedIterator<Product> iterator = container.GetItemQueryIterator<Product>(query, requestOptions: queryOptions);

Sie können die RU-Nutzung auch beobachten, indem Sie die Eigenschaft RequestCharge der einzelnen Objekte vom Typ FeedResponse abrufen, die den einzelnen Ergebnisseiten zugeordnet sind. Wenn Sie die Anforderungsgebühren aggregieren, erhalten Sie die gesamte Anforderungsgebühr für die gesamte Abfrage. Bei der ersten Abfrage wird ähnlich wie bei Punktlesevorgängen die übliche Anzahl von Anforderungseinheiten verwendet. Bei allen weiteren Abfragen werden keine Anforderungseinheiten verwendet, bis die Daten im Cache ablaufen.

double totalRequestCharge = 0;
while(iterator.HasMoreResults)
{
    FeedResponse<Product> response = await iterator.ReadNextAsync();
    totalRequestCharge += response.RequestCharge;
    Console.WriteLine($"Request charge:\t\t{response.RequestCharge:0.00} RU/s");
}

Console.WriteLine($"Total request charge:\t{totalRequestCharge:0.00} RU/s");