Share via

استيعاب البيانات بشكل مجمع في Azure Cosmos DB ل Gremlin باستخدام مكتبة منفذ مجمعة

  • مقالة

ينطبق على: العفريت

غالبا ما تحتاج قواعد بيانات Microsoft Azure Active Directory Graph إلى استيعاب البيانات بكميات كبيرة لتحديث الرسم البياني بأكمله أو تحديث جزء منه. يهدف Azure Cosmos DB، وهي قاعدة بيانات موزعة والعمود الفقري ل Azure Cosmos DB ل Gremlin، إلى الأداء الأفضل عندما يتم توزيع الأحمال بشكل جيد. صُممت مكتبات المنفّذ المجمّع في Azure Cosmos DB لاستغلال هذه الإمكانية الفريدة لـ Azure Cosmos DB وتوفير الأداء الأمثل. لمزيد من المعلومات، راجع تقديم دعم مجمّع في عدة تطوير البرامج Microsoft .NET.

في هذا البرنامج التعليمي، ستتعلم كيفية استخدام مكتبة المنفذ المجمع Azure Cosmos DB لاستيراد كائنات الرسم البياني وتحديثها إلى حاوية Azure Cosmos DB ل Gremlin. أثناء هذه العملية، يمكنك استخدام المكتبة لإنشاء عناصر القِمة والحافة برمجيًا ثم إدراج عناصر متعددة لكل طلب شبكة.

بدلًا من إرسال استعلامات Gremlin إلى قاعدة بيانات، حيث تُقيّم الأوامر ثم تُنفّذ واحدة تلو الأخرى، يمكنك استخدام مكتبة المنفّذ المجمّع لإنشاء العناصر محليًا والتحقق منها. بعد أن تُهيئ المكتبة عناصر الرسم البياني، فإنها تتيح لك إرسالهم إلى خدمة قاعدة البيانات بشكل تسلسلي.

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

تتوفر مكتبة المنفّذ المجمّع الآن بالأشكال التالية.

.NET

المتطلبات الأساسية

قبل أن تبدأ، تأكد من أن لديك ما يلي:

استنساخ

شغّل الأمر التالي لاستخدام هذه العينة:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

للحصول على العينة، انتقل إلى .\azure-cosmos-graph-bulk-executor\dotnet\src\.

العينة


IGraphBulkExecutor graphBulkExecutor = new GraphBulkExecutor("MyConnectionString", "myDatabase", "myContainer");

List<IGremlinElement> gremlinElements = new List<IGremlinElement>();
gremlinElements.AddRange(Program.GenerateVertices(Program.documentsToInsert));
gremlinElements.AddRange(Program.GenerateEdges(Program.documentsToInsert));
BulkOperationResponse bulkOperationResponse = await graphBulkExecutor.BulkImportAsync(
    gremlinElements: gremlinElements,
    enableUpsert: true);

تنفيذ

عدّل المعلمات كما هو موضح في الجدول التالي:

المعلمة الوصف
ConnectionString سلسلة اتصال الخدمة الخاصة بك، والتي ستجدها في قسم Keys في حساب Azure Cosmos DB for Gremlin. نُسّق على أنه AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName أسماء قاعدة البيانات والحاوية الهدف.
DocumentsToInsert عدد المستندات التي ستُنشأ (ذات الصلة فقط بالبيانات الاصطناعية).
PartitionKey يضمن تحديد مفتاح قسم مع كل مستند أثناء استيعاب البيانات.
NumberOfRUs له صلة فقط إذا لم تتواجد الحاوية بالفعل وتحتاج إلى إنشائها أثناء التنفيذ.

نزّل نموذج التطبيق الكامل في Microsoft .NET.

Java

استخدام العينة

يوضح نموذج التطبيق التالي كيفية استخدام حزمة GraphBulkExecutor. تستخدم العينات إما التعليقات التوضيحية لعنصر المجال أو عناصر POJO (عنصر Java القديم العادي) مباشرة. نُوصى بتجربة كلا الأسلوبين لتحديد أيهما يلبي متطلبات التنفيذ والأداء بشكل أفضل.

استنساخ

لاستخدام العينة، شغّل الأمر التالي:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

للحصول على العينة، انتقل إلى .\azure-cosmos-graph-bulk-executor\java\.

المتطلبات الأساسية

لتشغيل هذه العينة، ستحتاج إلى الحصول على البرنامج التالي:

  • OpenJDK 11
  • Maven
  • حساب Azure Cosmos DB مُكوّن لاستخدام واجهة برمجة التطبيقات Gremlin

العينة

private static void executeWithPOJO(Stream<GremlinVertex> vertices,
                                        Stream<GremlinEdge> edges,
                                        boolean createDocs) {
        results.transitionState("Configure Database");
        UploadWithBulkLoader loader = new UploadWithBulkLoader();
        results.transitionState("Write Documents");
        loader.uploadDocuments(vertices, edges, createDocs);
    }

التكوين

لتشغيل العينة، يُرجى الرجوع إلى التكوين التالي وتعديله حسب الحاجة.

يحدد ملف /resources/application.properties البيانات المطلوبة لتكوين Azure Cosmos DB. القيم المطلوبة موضحة في الجدول التالي:

الخاصية الوصف
sample.sql.host القيمة التي يوفرها Azure Cosmos DB. تأكد من أنك تستخدم عنوان URI لعدة تطوير البرامج Microsoft .NET، والذي ستجده في قسم "نظرة عامة" في حساب Azure Cosmos DB.
sample.sql.key يمكنك الحصول على المفتاح الأساسي أو الثانوي من قسم "المفاتيح" في حساب Azure Cosmos DB.
sample.sql.database.name اسم قاعدة البيانات داخل حساب Azure Cosmos DB لتشغيل العينة في مقابلها. إذا لم يُعثر على قاعدة البيانات، فستُنشئها عينة التعليمة البرمجية.
sample.sql.container.name اسم الحاوية داخل قاعدة البيانات لتشغيل العينة في مقابلها. إذا لم يُعثر على الحاوية، فستُنشئها عينة التعليمة البرمجية.
sample.sql.partition.path إذا احتجت إلى إنشاء الحاوية، فاستخدم هذه القيمة لتعريف المسار partitionKey.
sample.sql.allow.throughput ستُحدّث الحاوية لاستخدام قيمة معدل النقل المحددة هنا. إذا كنت تستكشف خيارات مختلفة لمعدل النقل لتلبية متطلبات الأداء، فتأكد من إعادة ضبط معدل النقل في الحاوية عند الانتهاء من الاستكشاف. هناك تكاليف مرتبطة بترك الحاوية مزودة بمعدل نقل أعلى.

تنفيذ

بعد تعديل التكوين وفقًا للبيئتك، شغّل الأمر التالي:

mvn clean package

لمزيد من الأمان، يمكنك أيضًا تشغيل اختبارات التكامل عن طريق تغيير قيمة skipIntegrationTests في ملف pom.xml إلى false.

بعد نجاح تشغيل اختبارات الوحدة، يمكنك تشغيل عينة التعليمات البرمجية:

java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d

يؤدي تشغيل الأمر السابق إلى تنفيذ العينة باستخدام دُفعة صغيرة (1000 قِمة و5000 حافة تقريبًا). استخدم وسيطات سطر الأوامر في الأقسام التالية لتعديل وحدات التخزين التي تعمل وإصدار العينة المطلوب تشغيله.

وسيطات سطر الأوامر

تتوفر العديد من وسيطات سطر الأوامر أثناء تشغيل هذه العينة كما هو موضح في الجدول التالي:

وسيطة الوصف
--vertexCount (-v) يخبر التطبيق بعدد قِمم الأشخاص المراد إنشاؤها.
--edgeMax (-e) يخبر التطبيق بالحد الأقصى لعدد الحواف المراد إنشاؤها لكل قِمة. يحدد المُنشئ عشوائيًا رقمًا من 1 إلى القيمة التي تقدمها.
--domainSample (-d) يخبر التطبيق بتشغيل العينة باستخدام بنيات مجال الشخص والعلاقة بدلاً من GraphBulkExecutors وGremlinVertex وGremlinEdge POJOs.
--createDocuments (-c) يخبر التطبيق باستخدام عمليات create. إذا لم تكن الوسيطة موجودة، فسيُعيّن التطبيق افتراضيًا لاستخدام العمليات upsert.

معلومات عينة مفصلة

قِمة الشخص

فئة الشخص هي عنصر مجال بسيط مُزيّن بعدة تعليقات توضيحية للمساعدة في التحويل إلى الفئة GremlinVertex، كما هو موضح في الجدول التالي:

التعليق التوضيحي للفئة الوصف
GremlinVertex يستخدم المعلمة الاختيارية label لتعريف جميع القِمم التي تُنشئها باستخدام هذه الفئة.
GremlinId يُستخدم لتحديد الحقل الذي سيُستخدم كقيمة ID. اسم الحقل في فئة الشخص هو ID، إلا إنه غير مطلوب.
GremlinProperty يُستخدم في حقل email لتغيير اسم الخاصية عند تخزينها في قاعدة البيانات.
GremlinPartitionKey يُستخدم لتحديد أي حقل في الفئة يحتوي على مفتاح القسم. يجب أن يتطابق اسم الحقل الذي توفره مع القيمة التي يُحددها مسار القسم على الحاوية.
GremlinIgnore يُستخدم لاستبعاد الحقل isSpecial من الخاصية التي كُتبت في قاعدة البيانات.

فئة RelationshipEdge

الفئة RelationshipEdge هي عنصر مجال متعدد الاستخدامات. باستخدام التعليق التوضيحي لتسمية مستوى الحقل، يمكنك إنشاء مجموعة ديناميكية من أنواع الحواف كما هو موضح في الجدول التالي:

التعليق التوضيحي للفئة الوصف
GremlinEdge تحدد الزخرفة GremlinEdge الموجودة على الفئة اسم الحقل لمفتاح القسم المحدد. عند إنشاء مستند حافة، تأتي القيمة المُعينة من معلومات القِمة المصدر.
GremlinEdgeVertex يُحدد مثيلين من GremlinEdgeVertex، مثيل لكل جانب من الحافة (المصدر والوجهة). تحتوي العينة على نوع بيانات الحقل مثل GremlinEdgeVertexInfo. المعلومات التي توفرها فئة GremlinEdgeVertex مطلوبة لإنشاء الحافة بشكل صحيح في قاعدة البيانات. قد يكون الخيار الآخر هو جعل نوع بيانات القِمم فئة مُزينة بالتعليقات التوضيحية GremlinVertex.
GremlinLabel تستخدم عينة الحافة حقلًا لتعريف القيمة label. تسمح بتعريف تسميات مختلفة لأنها تستخدم نفس فئة المجال الأساسية.

شرح الإخراج

ستنتهي وحدة التحكم من تشغيلها بسلسلة JSON تصف أوقات تشغيل العينة. تحتوي سلسلة JSON على المعلومات التالية:

سلسلة JSON الوصف
startTime System.nanoTime() عند بدء العملية.
endTime System.nanoTime() عند انتهاء العملية.
durationInNanoSeconds الفرق بين القيمتين endTime وstartTime.
المدة بالدقائق القيمة durationInNanoSeconds، تُحوّل إلى دقائق. القيمة durationInMinutes تُمثّل كرقم حُر وليس قيمة زمنية. على سبيل المثال، القيمة 2.5 ستُمثل دقيقتين و30 ثانية.
vertexCount حجم القِمم المُنشأة والتي يجب أن تتطابق مع القيمة التي مُررت في تنفيذ سطر الأوامر.
edgeCount حجم الحواف المُنشأة، وهو ليس ثابتًا وأُنشئ باستخدام عنصر عشوائي.
exception يُملأ فقط إذا طُرح استثناء عند محاولة إجراء التشغيل.

مصفوفة الحالات

تعطي مصفوفة الحالات نظرة ثاقبة على المدة التي تستغرقها كل خطوة في التنفيذ. الخطوات موضحة في الجدول التالي:

خطوات التنفيذ الوصف
إنشاء عينات القِمم الوقت المستغرق لتصنيع الحجم المطلوب من عناصر الأشخاص.
إنشاء عينات الحواف الوقت المستغرق لتصنيع عناصر العلاقة.
تكوين قاعدة البيانات الوقت المستغرق لتكوين قاعدة البيانات استنادًا إلى القيم المقدمة في application.properties.
كتابة المستندات الوقت المستغرق لكتابة المستندات في قاعدة البيانات.

تحتوي كل حالة على القيم التالية:

قيمة الحالة الوصف
stateName اسم الحالة التي أُبلغ عنها.
startTime القيمة System.nanoTime() عند بدء الحالة.
endTime القيمة System.nanoTime() عند انتهاء الحالة.
durationInNanoSeconds الفرق بين القيمتين endTime وstartTime.
durationInMinutes القيمة durationInNanoSeconds، تُحوّل إلى دقائق. القيمة durationInMinutes تُمثّل كرقم حُر وليس قيمة زمنية. على سبيل المثال، القيمة 2.5 ستُمثل دقيقتين و30 ثانية.

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