Zarządzanie poziomami spójności w usłudze Azure Cosmos DBManage consistency levels in Azure Cosmos DB

W tym artykule wyjaśniono, jak zarządzać poziomami spójności w usłudze Azure Cosmos DB.This article explains how to manage consistency levels in Azure Cosmos DB. Dowiesz się, jak skonfigurować domyślny poziom spójności, zastąpić spójność domyślną, ręcznie zarządzać tokenami sesji oraz jak rozumieć metrykę PBS (Probabilistically Bounded Staleness).You learn how to configure the default consistency level, override the default consistency, manually manage session tokens, and understand the Probabilistically Bounded Staleness (PBS) metric.

Uwaga

Ten artykuł został zaktualizowany o korzystanie z nowego modułu Azure PowerShell Az.This article has been updated to use the new Azure PowerShell Az module. Nadal możesz używać modułu AzureRM, który będzie nadal otrzymywać poprawki błędów do co najmniej grudnia 2020 r.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Aby dowiedzieć się więcej na temat nowego modułu Az i zgodności z modułem AzureRM, zobacz Wprowadzenie do nowego modułu Az programu Azure PowerShell.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Aby uzyskać instrukcje dotyczące instalacji modułu Az, zobacz Instalowanie programu Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

Konfigurowanie domyślnego poziomu spójnościConfigure the default consistency level

Domyślny poziom spójności jest poziomem spójności używanym domyślnie przez klientów.The default consistency level is the consistency level that clients use by default. Klienci zawsze mogą ją przesłonić.Clients can always override it.

Interfejs CLICLI

# create with a default consistency
az cosmosdb create --name <name of Cosmos DB Account> --resource-group <resource group name> --default-consistency-level Session

# update an existing account's default consistency
az cosmosdb update --name <name of Cosmos DB Account> --resource-group <resource group name> --default-consistency-level Eventual

PowerShellPowerShell

Ten przykład tworzy nowe konto usługi Azure Cosmos z włączoną obsługą wielu regionów zapisu w regionach Wschodnie stany USA i zachodnie stany USA.This example creates a new Azure Cosmos account with multiple write regions enabled, in East US and West US regions. Domyślny poziom spójności jest ustawiony na spójność sesji .The default consistency level is set to Session consistency.

$locations = @(@{"locationName"="East US"; "failoverPriority"=0},
             @{"locationName"="West US"; "failoverPriority"=1})

$iprangefilter = ""

$consistencyPolicy = @{"defaultConsistencyLevel"="Session"}

$CosmosDBProperties = @{"databaseAccountOfferType"="Standard";
                        "locations"=$locations;
                        "consistencyPolicy"=$consistencyPolicy;
                        "ipRangeFilter"=$iprangefilter;
                        "enableMultipleWriteLocations"="true"}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
  -ApiVersion "2015-04-08" `
  -ResourceGroupName "myResourceGroup" `
  -Location "East US" `
  -Name "myCosmosDbAccount" `
  -Properties $CosmosDBProperties

Portal AzureAzure portal

Aby wyświetlić lub zmodyfikować domyślny poziom spójności, zaloguj się do witryny Azure Portal.To view or modify the default consistency level, sign in to the Azure portal. Znajdź konto usługi Azure Cosmos i Otwórz domyślne okienko spójności .Find your Azure Cosmos account, and open the Default consistency pane. Wybierz odpowiedni poziom spójności jako nowe ustawienie domyślne, a następnie wybierz pozycję Zapisz.Select the level of consistency you want as the new default, and then select Save. Azure Portal udostępnia również wizualizację różnych poziomów spójności przy użyciu notatek muzycznych.The Azure portal also provides a visualization of different consistency levels with music notes.

Menu spójności w witrynie Azure Portal

Zastępowanie domyślnego poziomu spójnościOverride the default consistency level

Klienci mogą zastąpić domyślny poziom spójności, który jest ustawiony przez usługę.Clients can override the default consistency level that is set by the service. Poziom spójności można ustawić dla każdego żądania, który zastępuje domyślny poziom spójności ustawiony na poziomie konta.Consistency level can be set on a per request, which overrides the default consistency level set at the account level.

ZESTAW .NET SDK V2.NET SDK V2

// 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.CreateDocumentAsync(collectionUri, document, requestOptions);

ZESTAW .NET SDK V3.NET SDK V3

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

var response = await client.GetContainer(databaseName, containerName)
    .CreateItemAsync(
        item, 
        new PartitionKey(itemPartitionKey), 
        requestOptions);

Java Async SDKJava Async SDK

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

Java Sync SDKJava Sync SDK

// Override consistency at the client level
ConnectionPolicy connectionPolicy = new ConnectionPolicy();
DocumentClient client = new DocumentClient(accountEndpoint, accountKey, connectionPolicy, ConsistencyLevel.Eventual);

Node.js/JavaScript/TypeScript SDKNode.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 SDKPython 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)

Korzystanie z tokenów sesjiUtilize session tokens

Jeden z poziomów spójności w Azure Cosmos DB jest spójność sesji .One of the consistency levels in Azure Cosmos DB is Session consistency. Jest to domyślny poziom stosowany domyślnie do kont Cosmos.This is the default level applied to Cosmos accounts by default. Podczas pracy ze spójnością sesji klient będzie używać tokenu sesji wewnętrznie w przypadku każdego żądania odczytu/zapytania, aby zapewnić zachowanie ustawienia poziomu spójności.When working with Session consistency, the client will use a session token internally with each read/query request to ensure that the set consistency level is maintained.

Aby ręcznie zarządzać tokenami sesji, pobieraj token sesji z odpowiedzi i ustawiaj go dla poszczególnych żądań.To manage session tokens manually, get the session token from the response and set them per request. Jeśli nie chcesz ręcznie zarządzać tokenami sesji, nie musisz korzystać z tych przykładów.If you don't need to manage session tokens manually, you don't need to use these samples. Zestaw SDK automatycznie śledzi tokeny sesji.The SDK keeps track of session tokens automatically. Jeśli nie ustawisz tokenu sesji ręcznie, zestaw SDK domyślnie użyje najnowszego tokenu sesji.If you don't set the session token manually, by default, the SDK uses the most recent session token.

ZESTAW .NET SDK V2.NET SDK V2

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

ZESTAW .NET SDK V3.NET SDK V3

Container container = client.GetContainer(databaseName, collectionName);
ItemResponse<SalesOrder> response = await container.CreateItemAsync<SalesOrder>(salesOrder);
string sessionToken = response.Headers.Session;

ItemRequestOptions options = new ItemRequestOptions();
options.SessionToken = sessionToken;
ItemResponse<SalesOrder> response = await container.ReadItemAsync<SalesOrder>(salesOrder.Id, new PartitionKey(salesOrder.PartitionKey), options);

Java Async SDKJava Async SDK

// 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);

Java Sync SDKJava Sync SDK

// Get session token from response
ResourceResponse<Document> response = client.readDocument(documentLink, null);
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
RequestOptions options = new RequestOptions();
options.setSessionToken(sessionToken);
ResourceResponse<Document> response = client.readDocument(documentLink, options);

Node.js/JavaScript/TypeScript SDKNode.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 SDKPython 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)

Monitorowanie metryki PBS (Probabilistically Bounded Staleness)Monitor Probabilistically Bounded Staleness (PBS) metric

Jak ostateczna jest spójność ostateczna?How eventual is eventual consistency? W przypadku średniego przypadku można zaoferować nieaktualność w odniesieniu do historii wersji i czasu.For the average case, can we offer staleness bounds with respect to version history and time. Metryka probabilistically ograniczona (PBS) próbuje określić prawdopodobieństwo nieodświeżoności i pokazuje ją jako metrykę.The Probabilistically Bounded Staleness (PBS) metric tries to quantify the probability of staleness and shows it as a metric. Aby wyświetlić metrykę usługi PBS, przejdź do swojego konta usługi Azure Cosmos w Azure Portal.To view the PBS metric, go to your Azure Cosmos account in the Azure portal. Otwórz okienko metryki i wybierz kartę spójność . Spójrz na wykres o nazwie prawdopodobieństwo silnie spójnych odczytów w oparciu o obciążenie (zobacz PBS) .Open the Metrics pane, and select the Consistency tab. Look at the graph named Probability of strongly consistent reads based on your workload (see PBS).

Wykres PBS w witrynie Azure Portal

Następne krokiNext steps

Dowiedz się więcej o zarządzaniu konfliktami danych lub przejdź do następnej kluczowej koncepcji w usłudze Azure Cosmos DB.Learn more about how to manage data conflicts, or move on to the next key concept in Azure Cosmos DB. Zobacz następujące artykuły:See the following articles: