Azure Cosmos DB'de tutarlılık düzeylerini yönetme

Bu makalede Azure Cosmos DB'de tutarlılık düzeylerinin nasıl yönetileceğini açıklanmaktadır. Varsayılan tutarlılık düzeyini yapılandırmayı, varsayılan tutarlılığı geçersiz kılmayı, oturum belirteçlerini el ile yönetmeyi ve Olasılıksal Sınırlanmış Eskime (PBS) ölçümünü anlamayı öğreneceksiniz.

Hesap düzeyi tutarlılığınızı değiştirirken, uygulamalarınızı yeniden dağıtıp bu değişiklikleri uygulamak için gerekli kod değişikliklerini yaptığınızdan emin olun.

Uyarı

Azure ile etkileşim kurmak için Azure Az PowerShell modülünü kullanmanızı öneririz. Başlamak için bkz. Azure PowerShell'i yükleme. Az PowerShell modülüne nasıl geçeceğinizi öğrenmek için bkz. Azure PowerShell’i AzureRM’den Az’ye geçirme.

Varsayılan tutarlılık düzeyini yapılandırma

Varsayılan tutarlılık düzeyi hakkında daha fazla bilgi edinmek için bkz. Azure Cosmos DB'de tutarlılık düzeyleri.

Azure portalı

Varsayılan tutarlılık düzeyini görüntülemek veya değiştirmek için:

1. Azure portalınaoturum açın.

2. Azure Cosmos DB hesabınızı bulun ve Varsayılan tutarlılık bölmesini açın.

3. Yeni varsayılan olarak istediğiniz tutarlılık düzeyini seçin ve ardından Kaydet'i seçin.

Azure portalı, müzik notları ile farklı tutarlılık düzeylerinin görselleştirmesini de sağlar.

CLI

Oturum tutarlılığı ile bir Azure Cosmos DB hesabı oluşturun ve ardından varsayılan tutarlılığı güncelleştirin.

# Create a new account with Session consistency
az cosmosdb create --name $accountName --resource-group $resourceGroupName --default-consistency-level Session

# Update an existing account's default consistency
az cosmosdb update --name $accountName --resource-group $resourceGroupName --default-consistency-level Strong

PowerShell

Oturum tutarlılığı ile bir Azure Cosmos DB hesabı oluşturun ve ardından varsayılan tutarlılığı güncelleştirin.

# Create a new account with Session consistency
New-AzCosmosDBAccount -ResourceGroupName $resourceGroupName `
  -Location $locations -Name $accountName -DefaultConsistencyLevel "Session"

# Update an existing account's default consistency
Update-AzCosmosDBAccount -ResourceGroupName $resourceGroupName `
  -Name $accountName -DefaultConsistencyLevel "Strong"

Varsayılan tutarlılık düzeyini geçersiz kılma

Hizmet varsayılan tutarlılık düzeyini ayarlar, ancak istemciler bunu geçersiz kılabilir. Tutarlılık düzeyi istek başına olarak ayarlanabilir ve bu da hesap düzeyinde ayarlanan varsayılan tutarlılık düzeyini geçersiz kılar.

Tavsiye

Tutarlılık yalnızca SDK örneğinde veya istek düzeyinde gevşetilebilir . Daha zayıf tutarlılıktan daha güçlü tutarlılık düzeyine geçmek için Azure Cosmos DB hesabının varsayılan tutarlılığını güncelleştirin.

Tavsiye

Varsayılan tutarlılık düzeyini geçersiz kılma yalnızca SDK istemcisi içindeki okuma işlemleri için geçerlidir. Varsayılan olarak güçlü tutarlılık için yapılandırılmış bir hesap, verileri hesaptaki her bölgeye zaman uyumlu olarak yazmaya ve çoğaltmaya devam eder. SDK istemci örneği veya isteği Bu düzeyi Oturum veya daha zayıf tutarlılık ile geçersiz kıldığında, okuma işlemleri tek bir çoğaltma kullanılarak gerçekleştirilir. Daha fazla bilgi için bkz . Tutarlılık düzeyleri ve aktarım hızı.

.NET SDK

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

.NET SDK V3

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

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

Java V4 SDK

Async

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

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

Senkronizasyon

Java SDK V4 (Maven com.azure::azure-cosmos) Eşitleme API'si

CosmosClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildClient();

Java V2 SDK'ları

Async

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

Senkronizasyon

Java V2 SDK Eşitleme (Maven com.microsoft.azure::azure-documentdb)

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

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

# 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 SDK'sı

İstekte tutarlılık düzeyini tanımlayın:

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(),
})

Oturum belirteçlerini kullanma

Azure Cosmos DB'deki tutarlılık düzeylerinden biri oturum tutarlılığıdır. Bu düzey, Azure Cosmos DB hesaplarına uygulanan varsayılan düzeydir. Oturum tutarlılığıyla çalışırken, Azure Cosmos DB'ye yapılan her yeni yazma isteğine yeni bir SessionToken atanır. CosmosClient, ayarlanan tutarlılık düzeyinin korunmasını sağlamak için bu belirteci her okuma/sorgu isteğiyle dahili olarak kullanır.

Bazı senaryolarda bu oturumu kendiniz yönetmeniz gerekir. Birden çok düğüme sahip bir web uygulaması düşünün; her düğümün kendi CosmosClient örneği vardır. Bu düğümlerin aynı oturuma katılmasını istiyorsanız (kendi yazma işlemlerinizi web katmanları arasında tutarlı bir şekilde okuyabilmek için), yazma eyleminin FeedResponse<T> içindeki SessionToken'ini son kullanıcıya bir tanımlama bilgisi veya başka bir mekanizma kullanarak göndermeniz ve bu belirtecin web katmanına geri akışının yanı sıra en sonunda sonraki okumalar için CosmosClient'a iletilmesini sağlamanız gerekir. Azure Load Balancer gibi istekler arasında oturum bağımlılığı sağlamayan sıralı yük dengeleyici kullanıyorsanız, okuma işlemi, oturumun oluşturulduğu düğümden farklı bir düğüme ve yazma isteğinin gerçekleştirdiği yere denk gelebilir.

Azure Cosmos DB SessionToken'u geçirmezseniz, bir süre tutarsız okuma sonuçları elde edebilirsiniz.

Azure Cosmos DB'deki oturum belirteçleri bölüme bağlıdır, yani yalnızca bir bölümle ilişkilendirilir. Yazmalarınızı okuyabildiğinizden emin olmak için, ilgili öğeler için en son oluşturulan oturum belirtecini kullanın. Oturum belirteçlerini el ile yönetmek için yanıttan oturum belirtecini alın ve istek başına ayarlayın. Oturum belirteçlerini el ile yönetmeniz gerekmiyorsa bu örnekleri kullanmanız gerekmez. SDK, oturum belirteçlerini otomatik olarak izler. Oturum belirtecini el ile ayarlamazsanız, SDK varsayılan olarak en son oturum belirtecini kullanır.

.NET SDK

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

.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 V4 SDK

Async

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

Senkronizasyon

Java SDK V4 (Maven com.azure::azure-cosmos) Eşitleme API'si

// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class);
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);

Java V2 SDK'ları

Async

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

Senkronizasyon

Java V2 SDK Eşitleme (Maven com.microsoft.azure::azure-documentdb)

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

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

// 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,
})

Olasılıksal Olarak Sınırlanmış Eskime Ölçümünü İzleme

Nihai tutarlılık ne kadar kesindir? Ortalama durum için sürüm geçmişine ve zamana göre eskime sınırları sunabiliriz. Olasılıksal Sınırlanmış Eskime (PBS) ölçümü eskime olasılığını ölçmeye çalışır ve bunu bir ölçüm olarak gösterir.

PBS ölçümünü görüntülemek için:

1. Azure Portal'da Azure Cosmos DB hesabınıza gidin.

2. Ölçümler (Klasik) bölmesini açın ve Tutarlılık sekmesini seçin.

3. İş yükünüze göre güçlü tutarlı okuma olasılığı adlı grafiğe bakın (bkz. PBS).

Sonraki Adımlar

Azure Cosmos DB'de veri çakışmalarını yönetme veya sonraki anahtar kavramına geçme hakkında daha fazla bilgi edinin.

• Azure Cosmos DB'de Tutarlılık Düzeyleri
• Bölümleme ve yatay ölçeklendirme
• Çakışma çözümleme ilkelerini yönetme
• Modern dağıtılmış veritabanı sistemleri tasarımında tutarlılık dengeleri
• NoSQL için Azure Cosmos DB'de yüksek kullanılabilirlik (Güvenilirlik)
• Azure Cosmos DB hizmet düzeyi sözleşmeleri