Öğretici: NoSQL api'sini kullanarak Azure Cosmos DB genel dağıtımını ayarlama

  • Makale

ŞUNUN IÇIN GEÇERLIDIR: NoSQL

Bu makalede, Azure portal kullanarak Azure Cosmos DB genel dağıtımını ayarlamayı ve ardından NoSQL API'sini kullanarak bağlanmayı göstereceğiz.

Bu makale aşağıdaki görevleri kapsar:

  • Azure portalını kullanarak genel dağıtımı yapılandırma
  • NoSQL'ler için API kullanarak genel dağıtımı yapılandırma

Azure portalını kullanarak genel veritabanı bölgeleri ekleme

Azure Cosmos DB, dünya genelindeki tüm Azure bölgelerinde kullanılabilir. Veritabanı hesabınız için varsayılan tutarlılık düzeyini seçtikten sonra bir veya daha fazla bölgeyi (tercih ettiğiniz varsayılan tutarlılık düzeyine ve genel dağıtım gereksinimlerine bağlı olarak) ilişkilendirebilirsiniz.

  1. Azure portalında, soldaki çubuktan Azure Cosmos DB seçeneğine tıklayın.

  2. Azure Cosmos DB sayfasında, değiştirilecek veritabanı hesabını seçin.

  3. Hesap sayfasındaki menüden Verileri genel olarak çoğaltma seçeneğine tıklayın.

  4. Verileri genel olarak çoğaltma sayfasında, haritadaki bölgelere tıklayarak eklenecek veya kaldırılacak bölgeleri seçin ve sonra Kaydet’e tıklayın. Bölgeleri eklemenin bir maliyeti yoktur. Daha fazla bilgi için fiyatlandırma sayfasına veya Azure Cosmos DB ile verileri genel olarak dağıtma makalesine bakın.

    Haritadaki bölgelere tıklayarak bölgeler ekleyin veya kaldırın

İkinci bir bölge eklediğinizde, portaldaki Verileri genel olarak çoğaltma sayfasında El İle Yük Devretme seçeneği etkinleştirilir. Yük devretme işlemini test etmek veya birincil yazma bölgesini değiştirmek için bu seçeneği kullanabilirsiniz. Üçüncü bir bölge eklemenizin ardından, okuma için yük devretme sırasını değiştirebilmeniz için aynı sayfada Yük Devretme Öncelikleri seçeneği etkinleştirilir.

Genel veritabanı bölgelerini seçme

İki veya daha fazla bölge yapılandırma için iki yaygın senaryo vardır:

  1. Dünya nerede bulunurlarsa bulunsunlar, son kullanıcılara düşük gecikmeli veri erişimi sunma
  2. İş sürekliliği ve olağanüstü durum kurtarma (BCDR) için bölgesel dayanıklılık ekleme

Son kullanıcılara düşük gecikme sunmak için, uygulama kullanıcılarının bulunduğu yere karşılık gelen bölgelerde hem uygulamayı hem de Azure Cosmos DB’yi dağıtmanız önerilir.

BCDR için, Azure'da bölgeler arası çoğaltma: İş sürekliliği ve olağanüstü durum kurtarma makalesinde açıklanan bölge çiftlerine göre bölgelerin eklenmesi önerilir.

NoSQL api'sini kullanarak tercih edilen bölgeye bağlanma

Genel dağıtımdan yararlanmak için istemci uygulamaları, belge işlemlerini gerçekleştirmek için kullanılacak bölgelerin tercihe göre sıralanmış listesini belirtebilir. Azure Cosmos DB hesap yapılandırmasına, geçerli bölgesel kullanılabilirliğe ve belirtilen tercih listesine göre yazma ve okuma işlemlerini gerçekleştirmek için SQL SDK tarafından en iyi uç nokta seçilir.

SQL SDK’ları kullanılarak bağlantı başlatırken bu tercih listesi belirtilir. SDK'lar, Azure bölgelerinin sıralı bir listesi olan isteğe bağlı bir parametreyi PreferredLocations kabul eder.

SDK, tüm yazma işlemlerini otomatik olarak geçerli yazma bölgesine gönderir. Tüm okuma işlemleri tercih edilen konumlar listesindeki kullanılabilir ilk bölgeye gönderilir. İstek başarısız olursa, istemci listeyi bir sonraki bölgeye devredecektir.

SDK yalnızca tercih edilen konumlarda belirtilen bölgelerden okuma yapmaya çalışır. Bu nedenle, örneğin, Azure Cosmos DB hesabı dört bölgede kullanılabiliyorsa, ancak istemci içinde PreferredLocationsyalnızca iki okuma (yazma olmayan) bölge belirtiyorsa, içinde belirtilmeyen PreferredLocationsokuma bölgesinde okuma işlemi yapılmaz. Listede belirtilen PreferredLocations okuma bölgeleri kullanılamıyorsa, okuma işlemleri yazma bölgesinden sunulur.

Uygulama, SDK 1.8 ve üzeri sürümlerde kullanılabilen ve ReadEndpointiki özelliği WriteEndpoint denetleyerek SDK tarafından seçilen geçerli yazma uç noktasını ve okuma uç noktasını doğrulayabilir. PreferredLocations Özellik ayarlanmadıysa, tüm istekler geçerli yazma bölgesinden sunulur.

Tercih edilen konumları belirtmediyseniz ancak yöntemini kullandıysanız setCurrentLocation SDK, istemcinin çalıştığı geçerli bölgeye göre tercih edilen konumları otomatik olarak doldurur. SDK, bölgeleri bir bölgenin geçerli bölgeye yakınlığı temelinde sıralar.

.NET SDK

SDK herhangi bir kod değişikliği olmadan kullanılabilir. Bu durumda SDK hem okuma hem de yazma işlemlerini otomatik olarak geçerli yazma bölgesine yönlendirir.

.NET SDK’nın 1.8 ve sonraki sürümlerinde, DocumentClient oluşturucusu için ConnectionPolicy parametresi, Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations adlı bir özelliğe sahiptir. Bu özellik <string> Koleksiyonu türünde olup bölge adlarının listesini içermelidir. Dize değerleri , Sırasıyla ilk ve son karakterden önce veya sonra boşluk olmadan Azure Bölgeleri sayfasındaki bölge adı sütununa göre biçimlendirilir.

Geçerli yazma ve okuma uç noktaları sırasıyla DocumentClient.WriteEndpoint ve DocumentClient.ReadEndpoint içinde kullanılabilir.

Not

Uç noktaların URL’leri, uzun ömürlü sabitler olarak değerlendirilmemelidir. Bu noktada hizmet bunları güncelleştirebilir. SDK bu değişikliği otomatik olarak işler.

.NET V2 SDK kullanıyorsanız, tercih edilen bölgeyi ayarlamak için özelliğini kullanın PreferredLocations .

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Alternatif olarak özelliğini kullanabilir SetCurrentLocation ve SDK'nın yakınlık temelinde tercih edilen konumu seçmesini sağlayabilirsiniz.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Node.js/JavaScript

Not

Uç noktaların URL’leri, uzun ömürlü sabitler olarak değerlendirilmemelidir. Bu noktada hizmet bunları güncelleştirebilir. SDK bu değişikliği otomatik olarak işler.

Aşağıda Node.js/JavaScript için bir kod örneği verilmiştir.

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient{ endpoint, key, connectionPolicy: { preferredLocations } });

Python SDK'sı

Aşağıdaki kod, Python SDK'sını kullanarak tercih edilen konumların nasıl ayarlandığını gösterir:

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK'sı

Aşağıdaki kod, Java SDK'sını kullanarak tercih edilen konumların nasıl ayarlandığını gösterir:

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


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Spark 3 Bağlayıcısı

Tercih edilen bölgesel listeyi yapılandırmayıspark.cosmos.preferredRegionsList kullanarak tanımlayabilirsiniz, örneğin:

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.accountKey" -> cosmosMasterKey,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

REST

Bir veritabanı hesabı birden çok bölgede kullanılabilir duruma getirildikten sonra, istemciler bu URI üzerinde bir GET isteği gerçekleştirerek kullanılabilirliğini sorgulayabilir https://{databaseaccount}.documents.azure.com/

Hizmet, bölgelerin listesini ve çoğaltmalar için karşılık gelen Azure Cosmos DB uç nokta URI’lerini döndürür. Yanıtta geçerli yazma bölgesi belirtilir. Daha sonra istemci aşağıdaki gibi diğer tüm REST API istekleri için uygun uç noktayı seçebilir.

Örnek yanıt

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}
  • Tüm PUT, POST ve DELETE istekleri, belirtilen yazma URI’sine gitmelidir
  • Tüm GET'ler ve diğer salt okunur istekler (örneğin sorgular) istemcinin seçtiği herhangi bir uç noktaya gidebilir

Salt okunur bölgelere yönelik yazma istekleri, HTTP hata kodu 403 (“Yasak”) ile başarısız olur.

Yazma bölgesi istemcinin ilk bulma aşamasından sonra değişirse, önceki yazma bölgesine yapılan sonraki yazma işlemleri HTTP hata kodu 403 ("Yasak") ile başarısız olur. İstemci daha sonra güncelleştirilmiş yazma bölgesini almak için bölgelerin listesini ALIR (GET).

Hepsi bu kadar. Böylece bu öğretici tamamlanmış olur. Azure Cosmos DB’deki tutarlılık düzeyleri bölümünü okuyarak genel olarak çoğaltılan hesabınızın tutarlılığının nasıl yönetileceğini öğrenebilirsiniz. Ayrıca genel veritabanı çoğaltmasının Azure Cosmos DB’de nasıl çalıştığı hakkında daha fazla bilgi için bkz. Azure Cosmos DB ile verileri genel olarak dağıtma.

Sonraki adımlar

Bu öğreticide aşağıdakileri yaptınız:

  • Azure portalını kullanarak genel dağıtımı yapılandırma
  • NoSQL'ler için API kullanarak genel dağıtımı yapılandırma

Artık Azure Cosmos DB yerel öykünücüsünü kullanarak yerel olarak geliştirme konusunda bilgi almak için sonraki öğreticiye geçebilirsiniz.

Öykünücü ile yerel olarak geliştirme

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.