Delen via

Consistentieniveaus in Azure Cosmos DB beheren

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

Zie Consistentieniveaus in Azure Cosmos DB voor meer informatie over het standaardconsistentieniveau.

Het standaardconsistentieniveau weergeven of wijzigen:

  1. Meld u aan bij het Azure-portaal.

  2. Zoek uw Azure Cosmos DB-account en open het deelvenster Standaardconsistentie.

  3. Selecteer het consistentieniveau dat u als nieuwe standaard wilt gebruiken en selecteer Opslaan.

Azure Portal biedt ook een visualisatie van verschillende consistentieniveaus met muzieknotities.

Schermopname van het consistentiemenu in Azure Portal.

Het standaardconsistentieniveau overschrijven

De service stelt het standaardconsistentieniveau in, maar clients kunnen dit overschrijven. Het consistentieniveau kan per aanvraag worden ingesteld, waardoor het standaardconsistentieniveau op accountniveau wordt overschreven.

Aanbeveling

Het versoepelen van consistentie kan alleen plaatsvinden op het niveau van het SDK-exemplaar of de aanvraag. Als u wilt overstappen van zwakkere naar sterkere consistentie, werkt u de standaardconsistentie voor het Azure Cosmos DB-account bij.

Aanbeveling

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-clientexemplaar of het verzoek dit niveau overschrijdt met sessie- of zwakkere consistentie, worden lezingen 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)

Go Softwareontwikkelingskit

Consistentieniveau definiëren op de aanvraag:

container, _ := c.NewContainer("moviesdb", "movies")

container.NewQueryItemsPager("select * from c", azcosmos.NewPartitionKey(), &azcosmos.QueryOptions{
		ConsistencyLevel: azcosmos.ConsistencyLevelEventual.ToPtr(),
})

container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), "Pulp Fiction", &azcosmos.ItemOptions{
		ConsistencyLevel: azcosmos.ConsistencyLevelStrong.ToPtr(),
})

Sessietokens gebruiken

Een van de consistentieniveaus in Azure Cosmos DB is sessieconsistentie. Dit niveau is het standaardniveau dat 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 bij elke lees-/queryaanvraag om ervoor te zorgen dat het consistentieniveau van de set 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 overdraagt, kunt u een tijdje inconsistente leesresultaten ervaren.

Sessietokens in Azure Cosmos DB zijn partitiegebonden, wat betekent dat ze exclusief zijn gekoppeld aan één partitie. 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)

Go Softwareontwikkelingskit

// Get the session token from the create item response
resp, _ := container.CreateItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), movie, &azcosmos.ItemOptions{
	ConsistencyLevel: azcosmos.ConsistencyLevelSession.ToPtr(),
})

// Use the session token to read the item
container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), movieId, &azcosmos.ItemOptions{
	SessionToken: resp.SessionToken,
})

Bewaken van de probabilistisch gebonden stalenheidsmetriek

Hoe betrouwbaar 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.

Voor het bekijken van de PBS-metriek:

  1. Ga in de Azure Portal naar uw Azure Cosmos DB-account.

  2. Open het deelvenster Metrische gegevens (klassiek) en selecteer het tabblad Consistentie .

  3. Bekijk de grafiek genaamd Waarschijnlijkheid van sterk consistente leesbewerkingen op basis van uw workload (zie PBS).

Schermopname van de grafiek

Volgende stappen

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