Verwalten von Konsistenzebenen in Azure Cosmos DB

  • Artikel

GILT FÜR: NoSQL

In diesem Artikel wird beschrieben, wie Sie Konsistenzebenen in Azure Cosmos DB verwalten. Sie erfahren, wie Sie die Standardkonsistenzebene konfigurieren, die Standardkonsistenz außer Kraft setzen, Sitzungstoken manuell verwalten und sich mit der PBS-Metrik (Probabilistically Bounded Staleness) vertraut machen können.

Stellen Sie beim Ändern der Konsistenz auf Kontoebene Ihre Anwendungen unbedingt erneut bereit, und nehmen Sie alle erforderlichen Codeänderungen vor, um diese Änderungen anzuwenden.

Hinweis

Es wird empfohlen, das Azure Az PowerShell-Modul für die Interaktion mit Azure zu verwenden. Informationen zu den ersten Schritten finden Sie unter Installieren des Azure Az PowerShell-Moduls. Informationen zum Migrieren zum Az PowerShell-Modul finden Sie unter Migrieren von Azure PowerShell von AzureRM zum Az-Modul.

Konfigurieren der Standardkonsistenzebene

Die Standardkonsistenzebene ist die Konsistenzebene, die Clients standardmäßig verwenden.

Melden Sie sich zum Anzeigen oder Ändern der Standardkonsistenzebene beim Azure-Portal an. Navigieren Sie zu Ihrem Azure Cosmos DB-Konto, und öffnen Sie den Bereich Standardkonsistenz. Wählen Sie die Konsistenzebene aus, die Sie als neue Standardeinstellung verwenden möchten, und wählen Sie anschließend Speichern. Das Azure-Portal bietet auch eine Visualisierung verschiedener Konsistenzebenen mit Musiknoten.

Konsistenzmenü im Azure-Portal

Außerkraftsetzen der Standardkonsistenzebene

Clients können die vom Dienst festgelegte Standardkonsistenzebene außer Kraft setzen. Die Konsistenzebene kann auf Anforderung festgelegt werden. Dabei wird die auf Kontoebene festgelegte Standardkonsistenzebene überschrieben.

Tipp

Konsistenz kann nur auf der Ebene der SDK-Instanz oder der Anforderung gelockert werden. Aktualisieren Sie die Standardkonsistenz für das Azure Cosmos DB-Konto, um von einer schwächeren zu einer stärkeren Konsistenz zu gelangen.

Tipp

Das Außerkraftsetzen der Standardkonsistenzebene gilt nur für Lesevorgänge innerhalb des SDK-Clients. Ein Konto, das standardmäßig für starke Konsistenz konfiguriert ist, schreibt und repliziert Daten weiterhin synchron in jede Region im Konto. Wenn die SDK-Clientinstanz oder -anforderung dies mit Sitzungskonsistenz oder einer schwächeren Konsistenz überschreibt, werden Lesevorgänge mit einem einzigen Replikat ausgeführt. Weitere Informationen finden Sie unter Konsistenzebenen und Durchsatz.

.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 SDKs

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)

Verwenden von Sitzungstoken

Die Konsistenz Sitzung ist eine der Konsistenzebenen in Azure Cosmos DB. Dies ist die Standardebene, die standardmäßig auf Azure Cosmos DB-Konten angewendet wird. Bei Verwendung der Sitzungskonsistenz wird jeder neuen Schreibanforderung an Azure Cosmos DB ein neues Sitzungstoken (SessionToken) zugewiesen. Der CosmosClient verwendet dieses Token intern mit jeder Lese-/Abfrageanforderung, um sicherzustellen, dass die festgelegte Konsistenzebene beibehalten wird.

In einigen Szenarien müssen Sie diese Sitzung selbst verwalten. Stellen Sie sich eine Webanwendung mit mehreren Knoten vor. Jeder Knoten verfügt über eine eigene CosmosClient-Instanz. Wenn diese Knoten an derselben Sitzung teilnehmen sollen (damit Sie Ihre eigenen Schreibvorgänge konsistent über verschiedene Webebenen hinweg lesen können), müssen Sie das Sitzungstoken aus der Feedantwort (FeedResponse) <T> der Schreibaktion mithilfe eines Cookies oder eines anderen Mechanismus an den Endbenutzer senden und dieses Token für nachfolgende Lesevorgänge wieder zurück an die Webebene und schließlich an den CosmosClient senden. Wenn Sie einen Roundrobin-Lastenausgleich ohne Beibehaltung der Sitzungsaffinität zwischen Anforderungen verwenden, z. B. Azure Load Balancer, wird die Leseanforderung möglicherweise an einen anderen Knoten gesendet als an den für die Schreibanforderung verwendeten Knoten, auf dem die Sitzung erstellt wurde.

Wenn Sie das Azure Cosmos DB-Sitzungstoken nicht wie oben beschrieben weiterleiten, kann es sein, dass Sie für eine gewisse Zeit inkonsistente Leseergebnisse erhalten.

Sitzungstoken in Azure Cosmos DB sind partitionsgebunden, d. h. sie sind ausschließlich einer Partition zugeordnet. Um sicherzustellen, dass Sie Ihre Schreibvorgänge lesen können, verwenden Sie das Sitzungstoken, das zuletzt für die relevanten Elemente generiert wurde. Rufen Sie zum manuellen Verwalten von Sitzungstoken das Sitzungstoken aus der Antwort ab, und legen Sie es jeweils pro Anforderung fest. Wenn Sie Sitzungstoken nicht manuell verwalten müssen, müssen Sie diese Beispiele nicht verwenden. Das SDK verfolgt Sitzungstoken automatisch. Wenn Sie das Sitzungstoken nicht manuell festlegen, nutzt das SDK standardmäßig das zuletzt verwendete Sitzungstoken.

.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 SDKs

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)

Überwachen der PBS-Metrik (Probabilistically Bounded Staleness)

Wie letztlich ist letztliche Konsistenz? Im Normalfall können wir begrenzte Veraltung im Hinblick auf Versionsverlauf und Zeit anbieten. Die PBS-Metrik (Probabilistically Bounded Staleness) versucht, die Wahrscheinlichkeit der Veraltung zu bestimmen und zeigt sie als Metrik an.

Navigieren Sie zum Anzeigen der PBS-Metrik im Azure-Portal zu Ihrem Azure Cosmos DB-Konto. Öffnen Sie den Bereich Metriken (klassisch), und wählen Sie die Registerkarte Konsistenz aus. Sehen Sie sich dann den Graphen Wahrscheinlichkeit stark konsistenter Lesevorgänge basierend auf Ihrer Workload (siehe PBS) an.

PBS-Graph im Azure-Portal

Nächste Schritte

Informieren Sie sich über das Verwalten von Datenkonflikten, oder fahren Sie mit dem nächsten wichtigen Konzept von Azure Cosmos DB fort. Weitere Informationen finden Sie in folgenden Artikeln: