Mengelola tingkat konsistensi di Azure Cosmos DB

  • Artikel

BERLAKU UNTUK: NoSQL

Artikel ini menjelaskan cara mengelola tingkat konsistensi di Azure Cosmos DB. Anda akan mempelajari cara mengonfigurasi tingkat konsistensi default, mengganti konsistensi default, mengelola token sesi secara manual, dan memahami metrik Probabilistically Bounded Staleness (PBS).

Saat Anda mengubah konsistensi tingkat akun, pastikan Anda menyebarkan ulang aplikasi Anda dan membuat modifikasi kode yang diperlukan untuk menerapkan perubahan ini.

Catatan

Sebaiknya Anda menggunakan modul Azure Az PowerShell untuk berinteraksi dengan Azure. Lihat Menginstal Azure PowerShell untuk memulai. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Memigrasikan Azure PowerShell dari AzureRM ke Az.

Mengonfigurasi tingkat konsistensi default

Tingkat konsistensi default adalah tingkat konsistensi yang digunakan klien secara default.

Untuk melihat atau mengubah tingkat konsistensi default, masuk ke portal Microsoft Azure. Temukan akun Azure Cosmos DB Anda, dan buka panel Konsistensi default . Pilih tingkat konsistensi yang Anda inginkan sebagai default baru, lalu pilih Simpan. Portal Microsoft Azure juga menyediakan visualisasi tingkat konsistensi yang berbeda dengan catatan musik.

Menu konsistensi di portal Microsoft Azure

Mengganti tingkat konsistensi default

Klien dapat mengganti tingkat konsistensi default yang diatur oleh layanan. Tingkat konsistensi dapat diatur per permintaan, yang menggantikan tingkat konsistensi default yang diatur pada tingkat akun.

Tip

Konsistensi hanya dapat dilonggarkan pada instans SDK atau tingkat permintaan. Untuk berpindah dari konsistensi yang lebih lemah ke yang lebih kuat, perbarui konsistensi default untuk akun Azure Cosmos DB.

Tip

Mengambil alih tingkat konsistensi default hanya berlaku untuk membaca dalam klien SDK. Akun yang dikonfigurasi untuk konsistensi yang kuat secara default masih akan menulis dan mereplikasi data secara sinkron ke setiap wilayah akun. Ketika instans klien SDK atau permintaan mengambil alih ini dengan Sesi atau konsistensi yang lebih lemah, pembacaan akan dilakukan menggunakan satu replika. Lihat Tingkat konsistensi dan throughput untuk detail selengkapnya.

.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) API Asinkron


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

Java V2 SDK

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)

Menggunakan token sesi

Salah satu tingkat konsistensi dalam Azure Cosmos DB adalah konsistensi Sesi. Ini adalah tingkat default yang diterapkan ke akun Azure Cosmos DB secara default. Saat bekerja dengan konsistensi Sesi, setiap permintaan tulis baru ke Azure Cosmos DB diberi SessionToken baru. CosmosClient akan menggunakan token ini secara internal dengan setiap permintaan baca/kueri untuk memastikan bahwa tingkat konsistensi yang ditetapkan dipertahankan.

Dalam beberapa skenario Anda perlu mengelola Sesi ini sendiri. Pertimbangkan aplikasi web dengan beberapa node, setiap node akan memiliki instans CosmosClient sendiri. Jika ingin node ini berpartisipasi dalam sesi yang sama (agar dapat membaca tulisan Anda sendiri secara konsisten di seluruh tingkatan web) Anda harus mengirim SessionToken dari FeedResponse <T> tindakan tulis ke pengguna akhir menggunakan cookie atau mekanisme lain, dan membiarkan aliran token itu kembali ke tingkat web dan akhirnya ke CosmosClient untuk tindakan baca selanjutnya. Jika Anda menggunakan penyeimbang beban round-robin yang tidak mempertahankan afinitas sesi antara permintaan, seperti Azure Load Balancer, pembacaan berpotensi mendarat di node yang berbeda dengan permintaan tulis, tempat sesi dibuat.

Jika Anda tidak menyalurkan alur Azure Cosmos DB SessionToken seperti yang dijelaskan di atas, Anda bisa berakhir dengan hasil baca yang tidak konsisten untuk jangka waktu tertentu.

Token Sesi di Azure Cosmos DB terikat partisi, yang berarti secara eksklusif dikaitkan dengan satu partisi. Untuk memastikan Anda dapat membaca tulisan Anda, gunakan token sesi yang terakhir dibuat untuk item yang relevan. Untuk mengelola token sesi secara manual, dapatkan token sesi dari respons dan atur per permintaan. Jika tidak perlu mengelola token sesi secara manual, Anda tidak perlu menggunakan sampel ini. SDK terus melacak token sesi secara otomatis. Jika Anda tidak mengatur token sesi secara manual, secara default, SDK akan menggunakan token sesi terbaru.

.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) API Asinkron


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

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)

Memantau metrik Probabilistically Bounded Staleness (PBS)

Bagaimana konsistensi akhir pada akhirnya? Untuk kasus rata-rata, kami dapat memberikan batas keusangan sehubungan dengan riwayat dan waktu versi. Metrik Probabilistically Bounded Staleness (PBS) mencoba mengukur probabilitas keusangan dan menunjukkannya sebagai metrik.

Untuk melihat metrik PBS, buka akun Azure Cosmos DB Anda di portal Azure. Buka panel Metrik (Klasik), dan pilih tab Konsistensi . Lihat grafik bernama Probabilitas pembacaan yang sangat konsisten berdasarkan beban kerja Anda (lihat PBS).

Grafik PBS di portal Microsoft Azure

Langkah berikutnya

Pelajari lebih lanjut cara mengelola konflik data, atau beralih ke konsep utama berikutnya di Azure Cosmos DB. Lihat artikel berikut: