مشاركة عبر

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

  • مقالة

ينطبق على: NoSQL

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

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

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

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

  1. في مدخل Azure، في الشريط اليسار، اضغط على Azure Cosmos DB.

  2. في صفحة DB Cosmos Azure حدد حساب قاعدة البيانات للتعديل.

  3. في صفحة الحساب، اضغط على نسخ البيانات على نحو مماثل عالمياً من القائمة.

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

    اضغط على المناطق في الخريطة لإضافتها أو حذفها

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

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

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

  1. توفير وصول ذي زمن الانتقال البطيء إلى البيانات إلى المستخدمين النهائيين دون الاكتراث لمكان تواجدهم حول العالم
  2. إضافة المرونة الإقليمية لسياسة استمرارية تصريف الأعمال واسترداد البيانات بعد عطل فادح (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 V2 SDK، فاستخدم PreferredLocations الخاصية لتعيين المنطقة المفضلة.

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

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

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

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

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

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

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, aadCredentials: tokenCredential, connectionPolicy: { preferredLocations } });

Python SDK

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

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, credential=token_credential, connectionPolicy)

Java V4 SDK

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

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

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

مُعيّن Spark 3

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

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "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.

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

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

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

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

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

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