Cara mengonfigurasi cache terintegrasi Azure Cosmos DB

BERLAKU UNTUK: NoSQL

Artikel ini menjelaskan cara memprovisi gateway khusus, mengonfigurasi cache terintegrasi, dan menyambungkan aplikasi Anda.

Prasyarat

• Jika Anda tidak memiliki langganan Azure, buatlah akun gratis sebelum Anda memulai.
• Aplikasi yang sudah ada yang menggunakan Azure Cosmos DB. Jika Anda tidak memilikinya, berikut adalah beberapa contohnya.
• API Azure Cosmos DB yang ada untuk akun NoSQL.

Memprovisikan gateway khusus

1. Navigasi ke akun Azure Cosmos DB di portal Microsoft Azure dan pilih tab Gateway Khusus.

   

2. Isi formulir Gateway khusus dengan detail berikut:

   • Gateway Khusus - Aktifkan tombol ke Tersedia.
   • SKU - Pilih SKU dengan komputasi dan ukuran memori yang diperlukan. Cache terintegrasi akan menggunakan sekitar 50% memori, dan memori yang tersisa digunakan untuk metadata dan merutekan permintaan ke partisi backend.
   • Jumlah instans - Jumlah node. Untuk tujuan pengembangan, kami sarankan untuk memulai dengan satu node ukuran D4. Berdasarkan jumlah data yang perlu Anda simpan dalam cache dan untuk mencapai high availability, Anda dapat meningkatkan ukuran node setelah pengujian awal.

   

3. Pilih Simpan dan tunggu sekitar 5-10 menit agar provisi gateway khusus selesai. Setelah provisi selesai, Anda akan melihat pemberitahuan berikut:

   

Mengonfigurasi cache terintegrasi

Saat Anda membuat gateway khusus, cache terintegrasi akan diprovisikan secara otomatis.

1. Ubah string koneksi aplikasi Anda untuk menggunakan titik akhir gateway khusus yang baru.

   String koneksi gateway khusus yang diperbarui ada di bilah Kunci:

   

   Semua string koneksi gateway khusus mengikuti pola yang sama. Hapus documents.azure.com dari string koneksi asli Anda dan ganti dengan sqlx.cosmos.azure.com. Gateway khusus akan selalu memiliki string koneksi yang sama, meskipun Anda menghapus dan memprovisikan ulang.

   Anda tidak perlu mengubah string koneksi di semua aplikasi menggunakan akun DB Azure Cosmos yang sama. Misalnya, Anda dapat memiliki satu koneksi CosmosClient menggunakan mode gateway dan titik akhir gateway khusus sementara CosmosClient yang lain menggunakan mode langsung. Dengan kata lain, menambahkan gateway khusus tidak memengaruhi cara yang ada untuk tersambung ke Azure Cosmos DB.

2. Jika Anda menggunakan .NET atau Java SDK, atur mode koneksi ke mode gateway. Langkah ini tidak diperlukan untuk Python dan Node.js SDK karena tidak memiliki opsi tambahan untuk menyambungkan selain mode gateway.

Catatan

Jika Anda menggunakan versi .NET atau Java SDK terbaru, mode koneksi defaultnya adalah mode langsung. Untuk menggunakan cache terintegrasi, Anda harus mengganti default ini.

Menyesuaikan konsistensi permintaan

Anda harus memastikan konsistensi permintaan adalah sesi atau kejadian. Jika tidak, permintaan akan selalu melewati cache terintegrasi. Cara termudah untuk mengonfigurasi konsistensi khusus untuk semua operasi baca adalah dengan menetapkannya di tingkat akun. Anda juga dapat mengonfigurasi konsistensi di tingkat permintaan, yang direkomendasikan jika Anda hanya ingin subkumpulan bacaan Anda menggunakan cache terintegrasi.

Sesuaikan MaxIntegratedCacheStaleness

Konfigurasikan MaxIntegratedCacheStaleness, yang merupakan waktu maksimum di mana Anda bersedia untuk mentolerir data cache kedaluarsa. Disarankan untuk mengatur MaxIntegratedCacheStaleness setingkat mungkin karena akan meningkatkan kemungkinan pembacaan dan kueri titik berulang dapat berupa hit cache. Jika Anda menyetel MaxIntegratedCacheStaleness ke 0, permintaan baca Anda akan tidak pernah menggunakan cache terintegrasi, terlepas dari tingkat konsistensinya. Bila tidak dikonfigurasi, default MaxIntegratedCacheStaleness adalah 5 menit.

Catatan

Dapat MaxIntegratedCacheStaleness diatur setingging 10 tahun. Dalam praktiknya, nilai ini adalah keusangan maksimum dan cache dapat diatur ulang lebih cepat karena mulai ulang simpul yang mungkin terjadi.

Menyesuaikan MaxIntegratedCacheStaleness didukung dalam versi ini dari setiap SDK:

SDK	Versi yang didukung
.NET SDK v3	>= 3.30.0
Java SDK v4	>= 4.34.0
Node.js SDK	>=3.17.0
Python SDK	>=4.3.1

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(30) 
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setMaxIntegratedCacheStaleness(Duration.ofMinutes(30));
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

 const queryRequestOptions = {
   maxIntegratedCacheStalenessInMs: 1800000 };
 const querySpec = {
   query: "SELECT * from c"
 };
 const { resources: items } = await container.items
   .query(querySpec, queryRequestOptions)
   .fetchAll();

Python

query = "SELECT * FROM c"
container.query_items(
    query=query,
    max_integrated_cache_staleness_in_ms=1800000
)

Melewati cache terintegrasi

BypassIntegratedCache Gunakan opsi permintaan untuk mengontrol permintaan mana yang menggunakan cache terintegrasi. Menulis, membaca titik, dan kueri yang melewati cache terintegrasi tidak akan menggunakan penyimpanan cache, menghemat ruang untuk item lain. Permintaan yang melewati cache masih dirutekan melalui gateway khusus. Permintaan ini dilayani dari backend dan RU biaya.

Melewati cache didukung dalam versi ini dari setiap SDK:

SDK	Versi yang didukung
.NET SDK v3	>= 3.39.0
Java SDK v4	>= 4.49.0
Node.js SDK	>= 4.1.0
Python SDK	Tidak didukung

.NET

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

Java

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setIntegratedCacheBypassed(true);
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

Node.js

    const queryRequestOptions = {
      bypassIntegratedCache: true };
    const querySpec = {
      query: "SELECT * from c"
    };
    const { resources: items, requestCharge: queryCharge } = await container.items
      .query(querySpec, queryRequestOptions)
      .fetchAll();

Python

Opsi permintaan cache terintegrasi bypass tidak tersedia di Python SDK.

Memverifikasi hit cache

Terakhir, Anda dapat memulai ulang aplikasi dan memverifikasi hit cache terintegrasi untuk pembacaan titik atau kueri berulang dengan melihat apakah biaya permintaan bernilai 0. Setelah Anda memodifikasi CosmosClient untuk menggunakan titik akhir gateway khusus, semua permintaan akan dirutekan melalui gateway khusus.

Untuk permintaan baca (bacaan atau kueri titik) untuk menggunakan cache terintegrasi, semua kriteria berikut harus benar:

• Klien Anda tersambung ke titik akhir gateway khusus
• Klien Anda menggunakan mode gateway (SDK Python dan Node.js selalu menggunakan mode gateway)
• Konsistensi untuk permintaan harus diatur ke sesi atau akhirnya

Catatan

Apakah Anda memiliki umpan balik tentang cache terintegrasi? Kami ingin mendengar pendapat Anda! Jangan ragu untuk berbagi umpan balik secara langsung dengan tim teknik Azure Cosmos DB: cosmoscachefeedback@microsoft.com

Langkah berikutnya

• FAQ cache terintegrasi
• Gambaran umum cache terintegrasi
• Gateway khusus