Azure Cosmos DB tümleşik önbelleğini yapılandırma

UYGULANANLAR: NoSQL

Bu makalede ayrılmış bir ağ geçidi sağlama, tümleşik önbelleği yapılandırma ve uygulamanızı bağlama işlemleri açıklanmaktadır.

Önkoşullar

• Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
• Azure Cosmos DB kullanan mevcut bir uygulama. Uygulamanız yoksa bazı örnekler aşağıda verilmiştir.
• NoSQL hesabı için mevcut bir Azure Cosmos DB API'si.

Ayrılmış ağ geçidini sağlama

1. Azure portalında bir Azure Cosmos DB hesabına gidin ve Ayrılmış Ağ Geçidi sekmesini seçin.

   

2. Ayrılmış ağ geçidi formunu aşağıdaki ayrıntılarla doldurun:

   • Ayrılmış Ağ Geçidi - Sağlanan'a geçiş düğmesini açın.
   • SKU - Gerekli işlem ve bellek boyutuna sahip bir SKU seçin. Tümleşik önbellek belleğin yaklaşık %50'sini kullanır ve kalan bellek meta veriler ve istekleri arka uç bölümlerine yönlendirmek için kullanılır.
   • Örnek sayısı - Düğüm sayısı. Geliştirme amacıyla D4 boyutunda bir düğümle başlamanızı öneririz. Önbelleğe almanız gereken veri miktarına bağlı olarak ve yüksek kullanılabilirlik elde etmek için ilk testten sonra düğüm boyutunu artırabilirsiniz.

   

3. Kaydet'i seçin ve ayrılmış ağ geçidi sağlama işleminin tamamlanması için yaklaşık 5-10 dakika bekleyin. Sağlama tamamlandığında aşağıdaki bildirimi görürsünüz:

   

Uygulamanızı tümleşik önbelleği kullanacak şekilde yapılandırma

Ayrılmış bir ağ geçidi sağladığınızda, tümleşik önbellek otomatik olarak oluşturulur. Tümleşik önbelleği kullanmaları gerekmiyorsa Azure Cosmos DB kullanarak tüm uygulamaları ayrılmış ağ geçidine bağlamanız gerekmez. Ayrılmış ağ geçidi eklemek, Azure Cosmos DB'ye bağlanmanın mevcut yollarını etkilemez. Örneğin, ağ geçidi modunu ve ayrılmış ağ geçidi uç noktasını kullanırken diğerinde doğrudan modu kullanan bir CosmosClient CosmosClient bağlantınız olabilir.

Rol tabanlı erişim denetimiyle kimlik doğrulaması

Ayrılmış ağ geçidi Azure Cosmos DB ile aynı izinleri, rol tanımlarını ve rol atamalarını kullanır. Azure Cosmos DB hesabınızda veri düzlemi işlemleri için yapılandırılmış rol tabanlı erişim denetimi (RBAC) zaten varsa, ayrılmış ağ geçidinde kimlik doğrulaması yapmak için de kullanabilirsiniz. Azure Cosmos DB veri düzlemi işlemleri için RBAC hakkında bilgi edinin.

Ayrılmış ağ geçidi uç noktasını, kimlik bilgilerini ve ağ geçidi bağlantı modunu yapılandırarak öğesini CosmosClient yapılandırın. Tüm ayrılmış ağ geçidi uç noktaları aynı deseni izler. Özgün uç noktanızdan kaldırın documents.azure.com ve ile sqlx.cosmos.azure.comdeğiştirin. Ayrılmış ağ geçidini kaldırıp yeniden oluştursanız bile her zaman aynı uç noktaya sahip olursunuz.

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<dedicated-gateway-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential, new CosmosClientOptions { ConnectionMode = ConnectionMode.Gateway });

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<dedicated-gateway-endpoint>")
            .gatewayMode()
            .credential(credential);
            .buildClient();
    }
}

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<dedicated-gateway-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential})

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

bağlantı dizesi ile kimlik doğrulaması

1. Uygulamanızın bağlantı dizesi yeni ayrılmış ağ geçidi uç noktasını kullanacak şekilde değiştirin.

   Güncelleştirilmiş ayrılmış ağ geçidi bağlantı dizesi Anahtarlar dikey penceresindedir:

   

   Tüm ayrılmış ağ geçidi bağlantı dizesi aynı deseni izler. Özgün bağlantı dizesi kaldırın documents.azure.com ve ile sqlx.cosmos.azure.comdeğiştirin. Ayrılmış ağ geçidini kaldırıp yeniden oluştursanız bile her zaman aynı bağlantı dizesi sahip olur.

2. .NET veya Java SDK kullanıyorsanız bağlantı modunu ağ geçidi moduna ayarlayın. Python ve Node.js SDK'ları için bu adım gerekli değildir çünkü ağ geçidi modunun yanı sıra başka bağlanma seçenekleri yoktur.

İstek tutarlılığını ayarlama

İstek tutarlılığının oturum veya nihai olduğundan emin olmanız gerekir. Aksi takdirde, istek her zaman tümleşik önbelleği atlar. Tüm okuma işlemleri için belirli bir tutarlılığı yapılandırmanın en kolay yolu bunu hesap düzeyinde ayarlamaktır. Tutarlılığı istek düzeyinde de yapılandırabilirsiniz. Bu, okumalarınızın yalnızca bir alt kümesinin tümleşik önbelleği kullanmasını istiyorsanız önerilir.

MaxIntegratedCacheStaleness ayarını yapın

eski önbelleğe alınmış verileri tolere etmek istediğiniz en uzun süre olan öğesini yapılandırın MaxIntegratedCacheStaleness. Yinelenen nokta okumalarının ve sorguların MaxIntegratedCacheStaleness önbellek isabetleri olma olasılığını artıracağından mümkün olduğunca yüksek olarak ayarlanması önerilir. 0 olarak ayarlarsanızMaxIntegratedCacheStaleness, tutarlılık düzeyinden bağımsız olarak okuma isteğiniz hiçbir zaman tümleşik önbelleği kullanmaz. Yapılandırılmadığında varsayılan MaxIntegratedCacheStaleness değer 5 dakikadır.

ayarının ayarlanması MaxIntegratedCacheStaleness her SDK'nın şu sürümlerinde desteklenir:

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

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

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

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

Tümleşik önbelleği atlama

Hangi isteklerin BypassIntegratedCache tümleşik önbelleği kullandığını denetlemek için istek seçeneğini kullanın. Tümleşik önbelleği atlayan yazma işlemleri, nokta okumaları ve sorgular önbellek depolama alanını kullanmaz ve diğer öğeler için alan tasarrufu sağlar. Önbelleği atlayan istekler hala ayrılmış ağ geçidi üzerinden yönlendirilir. Bu istekler arka uçtan ve maliyet RU'larından sunulur.

Önbelleğin atlanması her SDK'nın şu sürümlerinde desteklenir:

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

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

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

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

Önbellek isabetlerini doğrulama

Son olarak, istek ücretinin 0 olup olmadığını görerek uygulamanızı yeniden başlatabilir ve yinelenen nokta okumaları veya sorguları için tümleşik önbellek isabetlerini doğrulayabilirsiniz. Ayrılmış ağ geçidi uç noktasını kullanmak üzere öğesini CosmosClient değiştirdikten sonra, tüm istekler ayrılmış ağ geçidi üzerinden yönlendirilir.

Bir okuma isteğinin (nokta okuma veya sorgu) tümleşik önbelleği kullanabilmesi için aşağıdaki ölçütlerin tümü doğru olmalıdır:

• İstemciniz ayrılmış ağ geçidi uç noktasına bağlanır
• İstemciniz ağ geçidi modunu kullanıyor (Python ve Node.js SDK'lar her zaman ağ geçidi modunu kullanır)
• İsteğin tutarlılığı oturum veya nihai olarak ayarlanmalıdır

Sonraki adımlar

• Tümleşik önbellek hakkında SSS
• Tümleşik önbelleğe genel bakış
• Ayrılmış ağ geçidi