Gestire i livelli di coerenza in Azure Cosmos DB

  • Articolo

SI APPLICA A: NoSQL

Questo articolo illustra come gestire i livelli di coerenza in Azure Cosmos DB. Si apprenderà come configurare la coerenza predefinita, sostituire la coerenza predefinita, gestire manualmente i token di sessione e monitorare la metrica del decadimento ristretto probabilistico (Probabilistic Bounded Staleness, PBS).

Quando si modifica la coerenza a livello di account, assicurarsi di ridistribuire le applicazioni e apportare eventuali modifiche al codice necessarie per applicare queste modifiche.

Nota

È consigliabile usare il modulo Azure Az PowerShell per interagire con Azure. Per iniziare, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Configurare il livello di coerenza predefinito

Il livello di coerenza predefinito è il livello di coerenza che i client usano per impostazione predefinita.

Per visualizzare o modificare il livello di coerenza predefinito, accedere al portale di Azure. Individuare l'account Azure Cosmos DB e aprire il riquadro Coerenza predefinita. Selezionare il livello di coerenza desiderato come il nuovo valore predefinito e quindi selezionare Salva. Il portale di Azure offre anche una visualizzazione dei diversi livelli di coerenza con note musicali.

Menu relativo alla coerenza nel portale di Azure

Sostituire il livello di coerenza predefinito

Nei client è possibile impostare un livello di coerenza diverso dall'impostazione predefinita del servizio. Il livello di coerenza può essere impostato per ogni richiesta, che sostituisce il livello di coerenza predefinito impostato a livello di account.

Suggerimento

La coerenza può essere solo ridotta a livello di istanza o richiesta dell'SDK. Per passare da una coerenza più debole ad una più forte, aggiornare la coerenza predefinita per l'account Azure Cosmos DB.

Suggerimento

È possibile ignorare il livello di coerenza predefinito solo per le operazioni di lettura all'interno del client SDK. Un account configurato in modo predefinito per la coerenza assoluta continuerà a eseguire operazioni di scrittura e replica dei dati in modo sincrono in ogni area dell'account. Quando l'istanza o la richiesta del client SDK ignora questo aspetto con una coerenza di sessione o più debole, le operazioni di lettura verranno eseguite usando una singola replica. Per ottenere maggiori informazioni, consultare Livelli di coerenza e velocità effettiva.

.NET SDK

// Override consistency at the client level
documentClient = new DocumentClient(new Uri(endpoint), authKey, connectionPolicy, ConsistencyLevel.Eventual);

// Override consistency at the request level via request options
RequestOptions requestOptions = new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };

var response = await client.ReadDocumentAsync(collectionUri, document, requestOptions);

Java v4 SDK

API asincrona Java SDK V4 (Maven com.azure::azure-cosmos)


CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildAsyncClient();

Java V2 SDK

Async Java SDK V2 (Maven com.microsoft.azure::azure-cosmosdb)

// Override consistency at the client level
ConnectionPolicy policy = new ConnectionPolicy();

AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKey(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConsistencyLevel(ConsistencyLevel.Eventual)
                .withConnectionPolicy(policy).build();

Node.js/JavaScript/TypeScript SDK

// Override consistency at the client level
const client = new CosmosClient({
  /* other config... */
  consistencyLevel: ConsistencyLevel.Eventual
});

// Override consistency at the request level via request options
const { body } = await item.read({ consistencyLevel: ConsistencyLevel.Eventual });

Python SDK

# Override consistency at the client level
connection_policy = documents.ConnectionPolicy()
client = cosmos_client.CosmosClient(self.account_endpoint, {
                                    'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Eventual)

Utilizzare i token di sessione

Uno dei livelli di coerenza in Azure Cosmos DB è il livello di coerenza Sessione. Questo è il livello predefinito applicato agli account Azure Cosmos DB per impostazione predefinita. Quando si usa la coerenza della sessione, a ogni nuova richiesta di scrittura in Azure Cosmos DB viene assegnato un nuovo sessionToken. CosmosClient userà internamente questo token con ogni richiesta di lettura/query per assicurarsi che venga mantenuto il livello di coerenza impostato.

In alcuni scenari, è necessario gestire manualmente questa sessione. Si consideri un'applicazione Web con più nodi, ogni nodo avrà una propria istanza di CosmosClient. Se si vuole che questi nodi partecipino alla stessa sessione (per poter leggere le proprie scritture in modo coerente tra i livelli Web), è necessario inviare SessionToken da FeedResponse T> dell'azione di scrittura all'utente finale usando un cookie o un altro meccanismo e fare in modo che tale token torni al livello Web e infine CosmosClient per le letture<successive. Se si usa un servizio di bilanciamento del carico round robin che non mantiene l'affinità di sessione tra le richieste, ad esempio Azure Load Balancer, la lettura potrebbe potenzialmente raggiungere un nodo diverso per la richiesta di scrittura, in cui è stata creata la sessione.

Se non si scorre il sessionToken di Azure Cosmos DB, come descritto in precedenza, è possibile che si verifichino risultati di lettura incoerenti per un po'.

I token di sessione in Azure Cosmos DB sono associati alle partizioni, questo significa che sono associati esclusivamente a una partizione. Per assicurare che l'utente possa leggere le proprie operazioni di scrittura, usare il token di sessione generato più recentemente per gli elementi pertinenti. Per gestire i token di sessione manualmente, ottenere il token di sessione dalla risposta e impostarli per ogni richiesta. Se non si ha necessità di gestire manualmente i token di sessione, non è necessario usare questi esempi. L'SDK tiene traccia dei token di sessione automaticamente. Se non si imposta il token di sessione manualmente, per impostazione predefinita l'SDK usa il token di sessione più recente.

.NET SDK

var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"));
string sessionToken = response.SessionToken;

RequestOptions options = new RequestOptions();
options.SessionToken = sessionToken;
var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"), options);

Java v4 SDK

API asincrona Java SDK V4 (Maven com.azure::azure-cosmos)


// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setSessionToken(sessionToken);
CosmosItemResponse<JsonNode> response2 = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();

Java V2 SDK

Async Java SDK V2 (Maven com.microsoft.azure::azure-cosmosdb)

// Get session token from response
RequestOptions options = new RequestOptions();
options.setPartitionKey(new PartitionKey(document.get("mypk")));
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);
readObservable.single()           // we know there will be one response
  .subscribe(
      documentResourceResponse -> {
          System.out.println(documentResourceResponse.getSessionToken());
      },
      error -> {
          System.err.println("an error happened: " + error.getMessage());
      });

// Resume the session by setting the session token on RequestOptions
RequestOptions options = new RequestOptions();
requestOptions.setSessionToken(sessionToken);
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);

Node.js/JavaScript/TypeScript SDK

// Get session token from response
const { headers, item } = await container.items.create({ id: "meaningful-id" });
const sessionToken = headers["x-ms-session-token"];

// Immediately or later, you can use that sessionToken from the header to resume that session.
const { body } = await item.read({ sessionToken });

Python SDK

// Get the session token from the last response headers
item = client.ReadItem(item_link)
session_token = client.last_response_headers["x-ms-session-token"]

// Resume the session by setting the session token on the options for the request
options = {
    "sessionToken": session_token
}
item = client.ReadItem(doc_link, options)

Monitorare la metrica del decadimento ristretto probabilistico (Probabilistic Bounded Staleness, PBS)

Com'è la coerenza finale? Per il caso medio, è possibile offrire limiti di decadimento rispetto alla cronologia delle versioni e al tempo. La metrica del decadimento ristretto probabilistico (Probabilistic Bounded Staleness, PBS) cerca di quantificare la probabilità di decadimento e la mostra come metrica.

Per visualizzare la metrica PBS, passare all'account Azure Cosmos DB nel portale di Azure. Aprire il riquadro Metriche (versione classica) e selezionare la scheda Coerenza. Esaminare il grafico denominato Probabilità di letture con coerenza assoluta in base al carico di lavoro (vedere PBS).

Grafico PBS nel portale di Azure

Passaggi successivi

Scoprire di più su come gestire i conflitti di dati o passare al concetto chiave successivo di Azure Cosmos DB. Fai riferimento ai seguenti articoli: