البرنامج التعليمي: إعداد التوزيع العالمي ل Azure Cosmos DB باستخدام واجهة برمجة التطبيقات ل NoSQL

مقالة
06/01/2023

ينطبق على: NoSQL

في هذه المقالة، نعرض كيفية استخدام مدخل Microsoft Azure لإعداد التوزيع العالمي ل Azure Cosmos DB ثم الاتصال باستخدام واجهة برمجة التطبيقات ل NoSQL.

تتناول هذه المقالة المهام التالية:

تكوين التوزيع العمومي باستخدام مدخل Microsoft Azure
تكوين التوزيع العمومي باستخدام واجهة برمجة التطبيقات ل NoSQLs

إضافة مناطق قاعدة بيانات عمومية باستخدام مدخل Microsoft Azure

يتوافر Azure Cosmos DB في جميع مناطق Azure على المستوى العالمي. بعد تحديد مستوى التناسق الافتراضي لحساب قاعدة البيانات، يمكنك إقران منطقة واحدة أو أكثر (اعتمادا على اختيارك لمستوى التناسق الافتراضي واحتياجات التوزيع العالمية).

في مدخل Microsoft Azure، في الشريط اليسار، اضغط على Azure Cosmos DB.
في صفحة DB Cosmos Azure حدد حساب قاعدة البيانات للتعديل.
في صفحة الحساب، اضغط على نسخ البيانات على نحو مماثل عالمياً من القائمة.
في الصفحة نسخ البيانات على نحو مماثل عالمياً، حدد المناطق التي تريد إضافتها أو حذفها بالضغط على المناطق في الخريطة، ثم اضغط علىحفظ. يوجد تكلفة لإضافة المناطق، يُرجى مراجعة صفحة الأسعار أو توزيع البيانات عالمياً باستخدام مقالة Azure Cosmos DB وذلك لمزيد من المعلومات.

بمجرد إضافة منطقة ثانية، يتم تمكين خيار تجاوز الفشل اليدوي على صفحة النسخ المتماثل للبيانات عالمياً في المدخل. يمكنك استخدام هذا الخيار لاختبار عملية تجاوز الفشل أو تغيير منطقة الكتابة الأساسية. بمجرد إضافة منطقة ثالثة، يتم تمكين الخيار أولويات تجاوز الفشل على نفس الصفحة بحيث يمكنك تغيير ترتيب تجاوز الفشل للقراءات.

تحديد مناطق قاعدة البيانات العالمية

يوجد سيناريوهان شائعان فيما يخص تكوين منطقين أو أكثر:

توفير وصول ذي زمن الانتقال البطيء إلى البيانات إلى المستخدمين دون الاكتراث لمكان تواجدهم حول العالم
إضافة المرونة الإقليمية لسياسة استمرارية تصريف الأعمال واسترداد البيانات بعد عطل فادح (BCDR)

لتوفير زمن الانتقال البطيء للمستخدمين النهائيين، من المستحسن نشر كل من التطبيق وAzure Cosmos DB في المناطق التي تتوافق مع مكان وجود مستخدمي التطبيق.

بالنسبة إلى BCDR، يوصى بإضافة مناطق استناداً إلى أزواج المناطق الموضحة في مقالة النسخ المتماثل عبر المناطق في Azure: استمرارية الأعمال والتعافي من الكوارث.

الاتصال بمنطقة مفضلة باستخدام واجهة برمجة التطبيقات ل NoSQL

للاستفادة من التوزيع العمومي، يمكن لتطبيقات العميل تحديد قائمة التفضيلات المُرتبة للمناطق التي ستستخدمها لتنفيذ عمليات المستند. استناداً إلى تكوين حساب Azure Cosmos DB والتوفر الإقليمي الحالي وقائمة التفضيلات المُحددة، سيتم اختيار نقطة النهاية المثلى بواسطة SQL SDK لتنفيذ عمليات الكتابة والقراءة.

تُحدد قائمة التفضيلات هذه عند تهيئة اتصال باستخدام SQL SDKs. تقبل SDKs معلمة اختيارية PreferredLocations قائمة مُرتبة من مناطق Azure.

سيقوم SDK تلقائياً بإرسال كافة عمليات الكتابة إلى منطقة الكتابة الحالية. ستُرسل كافة القراءات إلى المنطقة المتوفرة الأولى في قائمة المواقع المفضلة. إذا فشل الطلب، فسيفشل العميل في إدراج القائمة إلى المنطقة التالية.

سيحاول SDK القراءة من المناطق المُحددة في المواقع المفضلة فقط. لذلك، على سبيل المثال، إذا كان حساب Azure Cosmos DB متوفرا في أربع مناطق، ولكن العميل يحدد فقط منطقتين للقراءة (غير كتابة) داخل PreferredLocations، فلن يتم تقديم أي قراءات خارج منطقة القراءة غير المحددة في PreferredLocations. إذا لم تتوفر مناطق القراءة المُحددة في القائمة PreferredLocations، فستُقدم قراءات خارج منطقة الكتابة.

يمكن للتطبيق التحقق من نقطة نهاية الكتابة الحالية وقراءة نقطة النهاية المُختارة بواسطة SDK عن طريق التحقق من اثنين من الخصائص، WriteEndpoint وReadEndpoint، المتوفرين في الإصدار SDK 1.8 وأحدث. إذا لم تُعين PreferredLocations الخاصية، فستُقدم كافة الطلبات من منطقة الكتابة الحالية.

إذا لم تحدد المواقع المفضلة ولكنك استخدمت setCurrentLocation الأسلوب، سيملأ SDK تلقائياً المواقع المفضلة استناداً إلى المنطقة الحالية التي يعمل فيها العميل. يُرتب SDK المناطق استناداً إلى تقارب المنطقة من المنطقة الحالية.

.NET SDK

يمكن استخدام SDK دون أي تغييرات في التعليمات البرمجية. في هذه الحالة، يوجه SDK تلقائياً القراءة والكتابة إلى منطقة الكتابة الحالية.

في الإصدار 1.8 والأحدث من .NET SDK، المعلمة ConnectionPolicy للدالة الإنشائية DocumentClient تحتوي على خاصية تسمى Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. هذه الخاصية من نوع مجموعة <string> ويجب أن تحتوي على قائمة بأسماء المناطق. تُنسق قيم السلسلة حسب عمود اسم المنطقة في صفحة مناطق Azure، دون مسافات قبل أو بعد الحرف الأول والأخير على التوالي.

تتوفر نقاط النهاية الحالية للكتابة والقراءة في DocumentClient.WriteEndpoint وDocumentClient.ReadEndpoint على التوالي.

ملاحظة

لا ينبغي اعتبار URL لنقاط النهاية كثوابت طويلة الأمد. قد تُحدّث الخدمة هذه في أي وقت. يعالج SDK هذا التغيير تلقائياً.

NET SDK. الإصدار 2
⁦⁩.NET SDK V3⁦⁩

إذا كنت تستخدم .NET V2 SDK، فاستخدم 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);

بدلاً من ذلك، يمكنك استخدام SetCurrentLocation الخاصية والسماح لـ SDK باختيار الموقع المفضل استناداً إلى التقارب.

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

إذا كنت تستخدم .NET V3 SDK، فاستخدم ApplicationPreferredRegions الخاصية لتعيين المنطقة المفضلة.


CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
options.ApplicationPreferredRegions = new List<string> {Regions.WestUS, Regions.WestUS2};

CosmosClient client = new CosmosClient(connectionString, options);

بدلاً من ذلك، يمكنك استخدام ApplicationRegion الخاصية والسماح لـ SDK باختيار الموقع المفضل استناداً إلى التقارب.

CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
// If the application is running in West US
options.ApplicationRegion = Regions.WestUS;

CosmosClient client = new CosmosClient(connectionString, options);

Node.js/JavaScript

ملاحظة

لا ينبغي اعتبار URL لنقاط النهاية كثوابت طويلة الأمد. قد تُحدّث الخدمة هذه في أي وقت. سيُعالج SDK هذا التغيير تلقائياً.

وأدناه مثال على التعليمة البرمجية Node.js/Javascript.

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

توضح التعليمة البرمجية التالية كيفية تعيين المواقع المفضلة باستخدام Python SDK:

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

Java V4 SDK

توضح التعليمة البرمجية التالية كيفية تعيين المواقع المفضلة باستخدام Java SDK:

غير متزامنة
متزامنة

⁧⁩Java SDK V4⁧⁩ (Maven ⁧⁩com.azure::azure-cosmos⁧⁩) واجهة برمجة التطبيقات غير المتزامنة


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

⁧⁩Java SDK V4⁧⁩ (Maven ⁧⁩com.azure::azure-cosmos⁧⁩) واجهة برمجة التطبيقات المتزامنة


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

CosmosClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildClient();

مُعيّن Spark 3

يمكن تحديد القائمة الإقليمية المفضلة باستخدامspark.cosmos.preferredRegionsListالتكوين، على سبيل المثال:

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

REST

بمجرد توفير حساب قاعدة البيانات في مناطق متعددة، فيمكن للعملاء الاستعلام عن توفره من خلال تنفيذ طلب GET على URI هذاhttps://{databaseaccount}.documents.azure.com/

ستُعيد الخدمة قائمة بالمناطق وURIs لنقطة نهاية Azure Cosmos DB المقابلة للنسخ المتماثلة. سيُشار إلى منطقة الكتابة الحالية في الاستجابة. يمكن للعميل بعد ذلك تحديد نقطة النهاية المناسبة لجميع طلبات واجهة برمجة تطبيقات REST الأخرى على النحو التالي.

مثال على الاستجابة

{
    "_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
}

يجب أن تذهب كافة طلبات PUT وPOST وDELETE إلى URI للكتابة الموضحة
قد تذهب كافة GETs وطلبات القراءة الأخرى فقط (على سبيل المثال الاستعلامات) إلى أي نقطة نهاية من اختيار العميل

ستفشل طلبات الكتابة إلى مناطق القراءة فقط مع رمز الخطأ HTTP 403 ("ممنوع").

إذا تغيرت منطقة الكتابة بعد مرحلة اكتشاف العميل الأولية، فستفشل عمليات الكتابة اللاحقة إلى منطقة الكتابة السابقة مع رمز الخطأ HTTP 403 ("ممنوع"). يجب أن "يحصل" العميل بعد ذلك على قائمة المناطق مرة أخرى للحصول على منطقة الكتابة المُحدثة.

هذا كل شيء، هذا يُكمل هذا البرنامج التعليمي. يمكنك معرفة كيفية إدارة تناسق حسابك العام المكرر من خلال قراءةمستويات التناسق في قاعدة بيانات Azure Cosmos DB. وللمزيد من المعلومات حول كيفية عمل النسخ المتماثل لقاعدة البيانات العالمية في قاعدة بيانات Azure Cosmos DB، راجع توزيع البيانات عالميّاً باستخدام قاعدة بيانات Azure Cosmos DB.

الخطوات التالية

تعلمت في هذا البرنامج التعليمي، ما يلي:

تكوين التوزيع العمومي باستخدام مدخل Microsoft Azure
تكوين التوزيع العمومي باستخدام واجهة برمجة التطبيقات ل NoSQLs

يمكنك الآن المتابعة إلى البرنامج التعليمي التالي لمعرفة كيفية التطوير محلياً باستخدام Azure Cosmos DB المحاكي محلياً.

التطوير محلياً مع المحاكي

هل تحاول القيام بتخطيط السعة للترحيل إلى Azure Cosmos DB؟ يمكنك استخدام معلومات حول مجموعة قاعدة البيانات الموجودة لتخطيط السعة.

إذا كان كل ما تعرفه هو عدد vcores والخوادم في مجموعة قاعدة البيانات الموجودة، فاقرأ عن ⁧⁩تقدير وحدات الطلب باستخدام vCores أو vCPUs⁧⁩
إذا كنت تعرف المعدلات النموذجية للطلب لحمل العمل الحالي في قاعدة بياناتك، فاقرأ عن ⁧⁩تقدير وحدات الطلب باستخدام مخطط السعة من Azure Cosmos DB⁧⁩

Share via