Abilitare la cache integrata

  • 10 minuti

Abilitare la Cache integrata

L'abilitazione della cache integrata viene eseguita in due passaggi principali:

  • Creazione di un gateway dedicato nell'account di Azure Cosmos DB for NoSQL
  • Aggiornamento del codice dell'SDK per usare il gateway per le richieste

Creare un gateway dedicato

Prima di tutto, è necessario effettuare il provisioning di un gateway dedicato nell'account. Questa azione può essere eseguita usando il portale e il riquadro Gateway dedicato.

Spostamento gateway dedicato aperto nel pannello Azure Cosmos DB

Durante il processo di provisioning, viene chiesto di configurare il numero di istanze del gateway e uno SKU. Queste impostazioni determinano il numero di nodi e le dimensioni di calcolo e memoria per ogni nodo del gateway. Il numero di nodi e lo SKU possono essere modificati in un secondo momento in base all'aumento della quantità di dati da memorizzare nella cache.

Opzioni di configurazione del gateway dedicato per SKU e numero di nodi

Dopo il provisioning del nuovo gateway, è possibile ottenere l'endpoint per il gateway.

Nota

L'endpoint del gateway è diverso dall'endpoint tipico usato con un client Azure Cosmos DB for NoSQL.

Aggiornare il codice .NET SDK

Per consentire al client .NET SDK di usare la cache integrata, è necessario verificare che siano vere tre condizioni:

  • Il client usa l'endpoint gateway dedicato anziché l'endpoint tipico
  • Il client è configurato per usare la modalità Gateway invece della modalità di connettività Direct predefinita
  • Il livello di coerenza del client deve essere impostato su session o su eventual

Innanzitutto, assicurarsi che l'endpoint sia impostato sull'endpoint del gateway'dedicato. In genere, il formato degli endpoint di Azure Cosmos DB for NoSQL è <cosmos-account-name>.documents.azure.com. Per il gateway dedicato, la struttura dell'endpoint è <cosmos-account-name>.sqlx.cosmos.azure.com.

Anziché usare una chiave dell'account, configurare l'SDK per l'uso di un'identità gestita per l'autenticazione. Il codice aggiornato segue.

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);

Nota

Assicurarsi che all'applicazione sia abilitata un'identità gestita e che alla suddetta sia stato concesso il ruolo Collaboratore dati predefinito di Cosmos DB nell'account Azure Cosmos DB.

Configurare le operazioni di lettura dei punti

Per configurare un'operazione di lettura dei punti per usare la cache integrata, è necessario creare un oggetto di tipo ItemRequestOptions. In questo oggetto è possibile impostare manualmente la proprietà ConsistencyLevel su ConsistencyLevel.Session o su ConsistencyLevel.Eventual. È quindi possibile usare la variabile options nella chiamata al metodo ReadItemAsync.

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);

Per osservare l'utilizzo delle unità richiesta, usare la proprietà RequestCharge della variabile response. La prima chiamata di questa operazione di lettura usa il numero previsto di unità richiesta. In questo esempio si tratterebbe di un'unità richiesta per un'operazione di lettura dei punti. Le richieste successive non usano alcuna unità richiesta perché viene eseguito il pull dei dati dalla cache fino alla scadenza.

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

Configurare le query

Per configurare una query per usare la cache integrata, creare un oggetto di tipo QueryRequestOptions. In questo oggetto si deve anche modificare manualmente il livello di coerenza. Passare quindi la variabile options alla chiamata al metodo 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);

È anche possibile osservare l'utilizzo delle unità richiesta ottenendo la proprietà RequestCharge di ogni oggetto FeedResponse associato a ogni pagina dei risultati. Se si aggregano gli addebiti per le richieste, si ottiene l'addebito totale delle richieste per l'intera query. In modo analogo alle letture dei punti, la prima query usa il numero tipico di unità richiesta. Le eventuali query aggiuntive non usano alcuna unità richiesta fino alla scadenza dei dati nella cache.

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");