Consistentieniveaus in Azure Cosmos DB beheren

  • Artikel

VAN TOEPASSING OP: NoSQL

In dit artikel wordt uitgelegd hoe u consistentieniveaus beheert in Azure Cosmos DB. U leert hoe u het standaardconsistentieniveau configureert, de standaardconsistentie overschrijft, handmatig sessietokens beheert en wat metrische PBS-gegevens (Probabilistically Bounded Staleness) zijn.

Wanneer u de consistentie op accountniveau wijzigt, moet u ervoor zorgen dat u uw toepassingen opnieuw implementeert en de benodigde codewijzigingen aanbrengt om deze wijzigingen toe te passen.

Notitie

Het wordt aanbevolen de Azure Az PowerShell-module te gebruiken om te communiceren met Azure. Zie Azure PowerShell installeren om aan de slag te gaan. Raadpleeg Azure PowerShell migreren van AzureRM naar Az om te leren hoe u naar de Azure PowerShell-module migreert.

Het standaardconsistentieniveau configureren

Het standaardconsistentieniveau is het consistentieniveau dat clients standaard gebruiken.

Als u het standaardconsistentieniveau wilt weergeven of wijzigen, moet u zich aanmelden bij de Azure-portal. Zoek uw Azure Cosmos DB-account en open het deelvenster Standaardconsistentie. Selecteer het consistentieniveau dat u als nieuwe standaard wilt gebruiken en selecteer Opslaan. Azure Portal biedt ook een visualisatie van verschillende consistentieniveaus met muzieknotities.

Menu Consistentie in de Azure-portal

Het standaardconsistentieniveau overschrijven

Clients kunnen het standaardconsistentieniveau dat is ingesteld door de service overschrijven. Het consistentieniveau kan per aanvraag worden ingesteld, waardoor het standaardconsistentieniveau op accountniveau wordt overschreven.

Tip

Consistentie kan alleen worden versoepeld op het SDK-exemplaar of aanvraagniveau. Als u wilt overstappen van zwakkere naar sterkere consistentie, werkt u de standaardconsistentie voor het Azure Cosmos DB-account bij.

Tip

Het overschrijven van het standaardconsistentieniveau is alleen van toepassing op leesbewerkingen binnen de SDK-client. Een account dat standaard is geconfigureerd voor sterke consistentie, schrijft en repliceert gegevens synchroon naar elke regio in het account. Wanneer het SDK-clientexemplaren of de aanvraag dit overschrijft met sessie of zwakkere consistentie, worden leesbewerkingen uitgevoerd met één replica. Zie consistentieniveaus en doorvoer voor meer informatie.

.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

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


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

Java V2 SDK's

Async Java V2 SDK (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)

Sessietokens gebruiken

Een van de consistentieniveaus in Azure Cosmos DB is sessieconsistentie . Dit is het standaardniveau dat standaard wordt toegepast op Azure Cosmos DB-accounts. Bij het werken met sessieconsistentie wordt aan elke nieuwe schrijfaanvraag naar Azure Cosmos DB een nieuw SessionToken toegewezen. De CosmosClient gebruikt dit token intern met elke lees-/queryaanvraag om ervoor te zorgen dat het ingestelde consistentieniveau behouden blijft.

In sommige scenario's moet u deze sessie zelf beheren. Overweeg een webtoepassing met meerdere knooppunten. Elk knooppunt heeft een eigen exemplaar van CosmosClient. Als u wilt dat deze knooppunten deelnemen aan dezelfde sessie (om uw eigen schrijfbewerkingen consistent te kunnen lezen tussen weblagen), moet u het SessionToken verzenden van FeedResponse<T> van de schrijfactie naar de eindgebruiker met behulp van een cookie of een ander mechanisme, en dat token terug naar de weblaag laten stromen en uiteindelijk cosmosClient voor volgende leesbewerkingen. Als u een round robin-load balancer gebruikt die geen sessieaffiniteit tussen aanvragen onderhoudt, zoals de Azure Load Balancer, kan de leesbewerking mogelijk op een ander knooppunt terechtkomen bij de schrijfaanvraag, waar de sessie is gemaakt.

Als u het Azure Cosmos DB SessionToken niet doorstroomt zoals hierboven beschreven, kunt u een tijdje inconsistente leesresultaten opleveren.

Sessietokens in Azure Cosmos DB zijn partitiegebonden, wat betekent dat ze uitsluitend aan één partitie zijn gekoppeld. Gebruik het sessietoken dat voor het laatst is gegenereerd voor de relevante items om ervoor te zorgen dat u uw schrijfbewerkingen kunt lezen. Als u sessietokens handmatig wilt beheren, haalt u het sessietoken op uit het antwoord en stelt u het in per aanvraag. Als u sessietokens niet handmatig hoeft te beheren, hoeft u deze voorbeelden niet te gebruiken. De SDK houdt sessietokens automatisch bij. Als u het sessietoken niet handmatig instelt, gebruikt de SDK standaard het meest recente sessietoken.

.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

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


// 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's

Async Java V2 SDK (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)

Metrische gegevens van aan waarschijnlijkheid gebonden veroudering (PBS) controleren

Hoe uiteindelijk is uiteindelijke consistentie? Voor het gemiddelde geval kunnen we verouderingsgrenzen bieden met betrekking tot versiegeschiedenis en -tijd. De pbs-meetwaarde (Probabilistically Bounded Staleness) probeert de waarschijnlijkheid van veroudering te kwantificeren en deze weer te geven als metrische waarde.

Als u de metrische PBS-gegevens wilt weergeven, gaat u naar uw Azure Cosmos DB-account in de Azure-portal. Open het deelvenster Metrische gegevens (klassiek) en selecteer het tabblad Consistentie. Bekijk de grafiek met de naam Waarschijnlijkheid van sterk consistente leesbewerkingen op basis van uw workload (zie PBS).

PBS-grafiek in de Azure-portal

Volgende stappen

Lees meer informatie over het beheer van gegevensconflicten of ga verder met het volgende sleutelbegrip in Azure Cosmos DB. Zie de volgende artikelen: