Come configurare la cache integrata di Azure Cosmos DB

SI APPLICA A: NoSQL

Questo articolo descrive come effettuare il provisioning di un gateway dedicato, configurare la cache integrata e connettere l'applicazione.

Prerequisiti

• Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
• Un'applicazione che usa Azure Cosmos DB. Se non è disponibile alcuna applicazione di questo tipo, ecco alcuni esempi.
• Un'API di Azure Cosmos DB per l'account NoSQL.

Effettuare il provisioning del gateway dedicato

1. Passare a un account Azure Cosmos DB nel portale di Azure e selezionare la scheda Gateway dedicato.

   

2. Compilare il modulo Gateway dedicato con i dettagli seguenti:

   • Gateway dedicato: impostare l'interruttore su Sottoposto a provisioning.
   • SKU: selezionare uno SKU con le dimensioni di calcolo e memoria necessarie. La cache integrata userà circa il 50% della memoria e la memoria rimanente viene usata per i metadati e le richieste di routing alle partizioni back-end.
   • Numero di istanze: numero di nodi. A scopo di sviluppo, è consigliabile iniziare con un nodo con dimensioni D4. In base alla quantità di dati che è necessario memorizzare nella cache e per ottenere una disponibilità elevata, è possibile aumentare le dimensioni del nodo dopo il test iniziale.

   

3. Selezionare Salva e attendere circa 5-10 minuti per il completamento del provisioning del gateway dedicato. Al termine del provisioning, verrà visualizzata la notifica seguente:

   

Configurazione della cache integrata

Quando si crea un gateway dedicato, viene automaticamente eseguito il provisioning di una cache integrata.

1. Modificare la stringa di connessione dell'applicazione per usare il nuovo endpoint del gateway dedicato.

   La stringa di connessione del gateway dedicato aggiornata si trova nel pannello Chiavi:

   

   Tutte le stringhe di connessione del gateway dedicato usano lo stesso modello. Rimuovere documents.azure.com dalla stringa di connessione originale e sostituirla con sqlx.cosmos.azure.com. Un gateway dedicato avrà sempre la stessa stringa di connessione, anche se la si rimuove e si esegue nuovamente il provisioning.

   Non è necessario modificare la stringa di connessione in tutte le applicazioni usando lo stesso account Azure Cosmos DB. Ad esempio, si potrebbe avere una connessione CosmosClient mediante la modalità gateway e l'endpoint del gateway dedicato, mentre un'altra connessione CosmosClient usa la modalità diretta. In altre parole, l'aggiunta di un gateway dedicato non influisce sulle modalità di connessione ad Azure Cosmos DB esistenti.

2. Se si usa .NET SDK o Java SDK, impostare la modalità di connessione sulla modalità gateway. Questo passaggio non è necessario per gli SDK Python e Node.js perché non hanno opzioni aggiuntive per la connessione oltre alla modalità gateway.

Nota

Se si usa la versione più recente di .NET SDK o Java SDK, la modalità di connessione predefinita è la modalità diretta. Per usare la cache integrata, è necessario eseguire l'override di questa impostazione predefinita.

Regolare la coerenza delle richieste

È necessario assicurarsi che la coerenza della richiesta sia di tipo sessione o finale. In caso contrario, la richiesta ignora sempre la cache integrata. Il modo più semplice per configurare una coerenza specifica per tutte le operazioni di lettura prevede la sua impostazione a livello di account. È anche possibile configurare la coerenza a livello di richiesta. Questa impostazione è consigliata se si vuole usare solo un subset delle letture per usare la cache integrata.

Nota

Se si usa Python SDK, è necessario impostare in modo esplicito il livello di coerenza per ogni richiesta. L'impostazione predefinita a livello di account non verrà applicata automaticamente.

Adjust MaxIntegratedCacheStaleness

Configurare MaxIntegratedCacheStaleness, ovvero il tempo massimo di tolleranza di dati non aggiornati memorizzati nella cache. È consigliabile impostare il parametro MaxIntegratedCacheStaleness sul valore più alto possibile perché così facendo si aumenta la probabilità che le letture di punti ripetuti e le query possano corrispondere a riscontri nella cache. Se si imposta MaxIntegratedCacheStaleness su 0, la richiesta di lettura non userà mai la cache integrata, indipendentemente dal livello di coerenza. Se non configurato, il valore predefinito di MaxIntegratedCacheStaleness è 5 minuti.

Nota

Il parametro MaxIntegratedCacheStaleness può essere impostato su un valore massimo pari a 10 anni. In pratica, questo valore corrisponde al decadimento massimo e la cache può essere reimpostata prima a causa degli eventuali riavvii del nodo.

La modifica di MaxIntegratedCacheStaleness è supportata nelle versioni seguenti di ogni SDK:

SDK	Versioni supportate
.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
)

Ignorare la cache integrata (anteprima)

Usare l'opzione di richiesta BypassIntegratedCache per controllare quali richieste usano la cache integrata. Le operazioni di scrittura, lettura di punti e query che ignorano la cache integrata non useranno l'archiviazione cache, risparmiando in questo modo spazio per altri elementi. Le richieste che ignorano la cache vengono comunque instradate tramite il gateway dedicato. Queste richieste vengono gestite dal back-end e dalle UR di costo.

Il bypass della cache è supportato nelle versioni seguenti di ogni SDK:

SDK	Versioni supportate
.NET SDK v3	>= 3.35.0 (anteprima)
Java SDK v4	>= 4.49.0
Node.js SDK	Non supportato
Python SDK	Non supportato

.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

L'opzione di richiesta di bypass della cache integrata non è disponibile in Node.js SDK.

Python

L'opzione di richiesta di bypass della cache integrata non è disponibile in Python SDK.

Verificare i riscontri nella cache

Infine, è possibile riavviare l'applicazione e verificare i riscontri nella cache integrata per le letture ripetute dei punti o le query visualizzando se l'addebito della richiesta è 0. Dopo aver modificato CosmosClient per usare l'endpoint del gateway dedicato, tutte le richieste verranno instradate tramite il gateway dedicato.

Affinché una richiesta di lettura (lettura di punti o query) utilizzi la cache integrata, tutti i criteri seguenti devono essere true:

• Il client si connette all'endpoint del gateway dedicato
• Il client usa la modalità gateway (Python SDK e Node.js SDK usano sempre la modalità gateway)
• La coerenza per la richiesta deve essere impostata su Sessione o Finale

Nota

Si desidera lasciare un feedback sulla cache integrata? Saremo lieti di riceverlo. È possibile condividere i feedback direttamente con il team di progettazione di Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Passaggi successivi

• Domande frequenti sulla cache integrata
• Panoramica della cache integrata
• Gateway dedicato