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:

   

Configurare l'applicazione per l'uso della cache integrata

Quando si effettua il provisioning di un gateway dedicato, viene creata automaticamente una cache integrata. Non è necessario connettere tutte le applicazioni usando Azure Cosmos DB al gateway dedicato se non è necessario usare la cache integrata. L'aggiunta di un gateway dedicato non influisce sulle modalità esistenti di connessione ad 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.

Eseguire l'autenticazione con il controllo degli accessi in base al ruolo

Il gateway dedicato usa le stesse autorizzazioni, definizioni di ruolo e assegnazioni di ruolo di Azure Cosmos DB. Se il controllo degli accessi in base al ruolo è già configurato per le operazioni del piano dati nell'account Azure Cosmos DB, è anche possibile usarlo per l'autenticazione nel gateway dedicato. Informazioni sul controllo degli accessi in base al ruolo per le operazioni del piano dati di Azure Cosmos DB.

CosmosClient Configurare l'utente impostando l'endpoint gateway dedicato, le credenziali e configurando la modalità di connettività del gateway. Tutti gli endpoint gateway dedicati seguono lo stesso modello. Rimuovere documents.azure.com dall'endpoint originale e sostituirlo con sqlx.cosmos.azure.com. Un gateway dedicato avrà sempre lo stesso endpoint, anche se viene rimosso e eseguito nuovamente il provisioning.

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

Importante

La modalità di connettività diretta è l'impostazione predefinita in .NET SDK. È necessario configurare in modo esplicito la modalità gateway per l'uso del gateway dedicato.

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

Importante

La modalità di connettività diretta è l'impostazione predefinita in Java SDK. È necessario configurare in modo esplicito la modalità gateway per l'uso del gateway dedicato.

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)

Eseguire l'autenticazione con stringa di connessione

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.

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.

Importante

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.

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

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

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

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