استخدم مكتبة .NET للمنفذ المجمع لإجراء عمليات المجموعة في Azure Cosmos DB

ينطبق على: NoSQL

إشعار

يتم الاحتفاظ بمكتبة المنفذ المجمع الموضحة في هذه المقالة للتطبيقات التي تستخدم إصدار .NET SDK 2.x. بالنسبة للتطبيقات الجديدة، يمكنك استخدام الدعم المجمع المتوفر مباشرة مع الإصدار 3.x من .NET SDK، ولا يتطلب أي مكتبة خارجية.

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

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

حاليا، يتم دعم مكتبة المنفذ المجمع من قبل Azure Cosmos DB ل NoSQL وواجهة برمجة التطبيقات لحسابات Gremlin فقط. توضح هذه المقالة كيفية استخدام مكتبة .NET للمنفذ المجمع مع واجهة برمجة التطبيقات لحسابات NoSQL. لمعرفة كيفية استخدام مكتبة .NET للمنفذ المجمع مع واجهة برمجة التطبيقات لحسابات Gremlin، راجع استيعاب البيانات بشكل مجمع في Azure Cosmos DB ل Gremlin باستخدام مكتبة منفذ مجمع.

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

• أحدث Visual Studio مع أحمال عمل تطوير Azure. يمكنك البدء باستخدام Visual Studio Community IDE المجاني. بادر بتمكين حمل عمل تطوير Azure أثناء إعداد Visual Studio.

• في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

• يمكنك تجربة Azure Cosmos DB مجانا دون اشتراك Azure. يمكنك أيضا تثبيت Azure Cosmos DB Emulator واستخدامه للتطوير والاختبار المحليين https://localhost:8081 باستخدام نقطة النهاية. يتم توفير المفتاح الأساسي في طلبات المصادقة.

• إنشاء حساب Azure Cosmos DB ل NoSQL باستخدام الخطوات الموضحة في قسم إنشاء حساب Azure Cosmos DB من التشغيل السريع: مكتبة عميل Azure Cosmos DB ل NoSQL ل .NET.

استنساخ نموذج التطبيق

الآن دعنا ننتقل إلى العمل مع التعليمات البرمجية عن طريق تنزيل نموذج تطبيق .NET من GitHub. ينفذ هذا التطبيق عمليات مجمعة على البيانات المخزنة في حساب Azure Cosmos DB الخاص بك. لاستنساخ التطبيق، افتح موجه الأوامر، وانتقل إلى الدليل حيث تريد نسخه، ثم قم بتشغيل الأمر التالي:

git clone https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started.git

يحتوي المستودع المستنسخ على عينتين، BulkImportSample و BulkUpdateSample. يمكنك فتح أي من نماذج التطبيقات، وتحديث سلسلة الاتصال في ملف App.config باستخدام سلسلة الاتصال حساب Azure Cosmos DB الخاص بك، وبناء الحل، وتشغيله.

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

استيراد البيانات المجمعة إلى حساب Azure Cosmos DB

1. انتقل إلى المجلد BulkImportSample وافتح ملف BulkImportSample.sln .

2. يتم استرداد سلاسل اتصال Azure Cosmos DB من ملف App.config كما هو موضح في الكود التالي:

   private static readonly string EndpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
   private static readonly string AuthorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];
   private static readonly string DatabaseName = ConfigurationManager.AppSettings["DatabaseName"];
   private static readonly string CollectionName = ConfigurationManager.AppSettings["CollectionName"];
   private static readonly int CollectionThroughput = int.Parse(ConfigurationManager.AppSettings["CollectionThroughput"]);
   

   يقوم المستورد المجمع بإنشاء قاعدة بيانات جديدة وحاوية مع اسم قاعدة البيانات واسم الحاوية وقيم سرعة النقل المحددة في ملف App.config.

3. بعد ذلك، تتم تهيئة الكائن DocumentClient باستخدام وضع اتصال TCP المباشر:

   ConnectionPolicy connectionPolicy = new ConnectionPolicy
   {
      ConnectionMode = ConnectionMode.Direct,
      ConnectionProtocol = Protocol.Tcp
   };
   DocumentClient client = new DocumentClient(new Uri(endpointUrl),authorizationKey,
   connectionPolicy)
   

4. تتم تهيئة الكائن BulkExecutor بقيمة إعادة محاولة عالية لوقت الانتظار والطلبات المقيدة. ثم يتم تعيينها إلى 0 لتمرير التحكم في الازدحام إلى BulkExecutor طوال مدة بقائها.

   // Set retry options high during initialization (default values).
   client.ConnectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 30;
   client.ConnectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 9;
   
   IBulkExecutor bulkExecutor = new BulkExecutor(client, dataCollection);
   await bulkExecutor.InitializeAsync();
   
   // Set retries to 0 to pass complete control to bulk executor.
   client.ConnectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 0;
   client.ConnectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 0;
   

5. يستدعي التطبيق واجهة برمجة تطبيقات BulkImportAsync . توفر مكتبة .NET تحميلين زائدين من واجهة برمجة تطبيقات الاستيراد المجمع - أحدهما يقبل قائمة بمستندات JSON المتسلسلة والآخر يقبل قائمة بمستندات POCO التي تم إلغاء تسلسلها. لمعرفة المزيد حول تعريفات كل من هذه الأساليب ذات التحميل الزائد، راجع وثائق واجهة برمجة التطبيقات.

   BulkImportResponse bulkImportResponse = await bulkExecutor.BulkImportAsync(
     documents: documentsToImportInBatch,
     enableUpsert: true,
     disableAutomaticIdGeneration: true,
     maxConcurrencyPerPartitionKeyRange: null,
     maxInMemorySortingBatchSize: null,
     cancellationToken: token);
   

   يقبل أسلوب BulkImportAsync المعلمات التالية:

   المعلمة‬	الوصف
   enableUpsert	علامة لتمكين عمليات الإخراج على المستندات. إذا كان هناك مستند بالمعرف المحدد موجود بالفعل، فسيتم تحديثه. بشكل افتراضي، يتم تعيينه على خطأ.
   تعطيلAutomaticIdGeneration	علامة لتعطيل الإنشاء التلقائي للمعرف. بشكل افتراضي، يتم تعيينه على صواب.
   maxConcurrencyPerPartitionKeyRange	الحد الأقصى لدرجة التزامن لكل نطاق مفتاح قسم. يؤدي الإعداد إلى قيمة خالية إلى استخدام المكتبة لقيمة افتراضية تبلغ 20.
   maxInMemorySortingBatchSize	الحد الأقصى لعدد المستندات التي يتم سحبها من عداد المستندات، والذي يتم تمريره إلى استدعاء API في كل مرحلة. لمرحلة الفرز في الذاكرة التي تحدث قبل الاستيراد المجمع. يؤدي تعيين هذه المعلمة إلى قيمة خالية إلى استخدام المكتبة للقيمة الدنيا الافتراضية (documents.count، 1000000).
   رمز الإلغاء	رمز الإلغاء للخروج بأمان من عملية الاستيراد المجموعة.

تعريف كائن استجابة الاستيراد المجمع
تحتوي نتيجة استدعاء واجهة برمجة التطبيقات للاستيراد المجمع على السمات التالية:

المعلمة‬	الوصف
NumberOfDocumentsImported (طويل)	العدد الإجمالي للمستندات التي تم استيرادها بنجاح من إجمالي المستندات التي تم توفيرها لاستدعاء واجهة برمجة تطبيقات الاستيراد المجمّع.
TotalRequestUnitsConsumed (مزدوج)	إجمالي وحدات الطلب (RU) التي يتم استهلاكها بواسطة استدعاء واجهة برمجة تطبيقات الاستيراد المجمّع.
TotalTimeTaken (TimeSpan)	إجمالي الوقت الذي يستغرقه استدعاء واجهة برمجة تطبيقات الاستيراد المجمّع لإكمال التنفيذ.
BadInputDocuments (عنصر> القائمة<)	قائمة المستندات غير المنسقة التي لم يتم استيرادها بنجاح في استدعاء واجهة برمجة التطبيقات للاستيراد المجمع. أصلح المستندات التي تم إرجاعها وأعد محاولة الاستيراد. تتضمن المستندات غير المنسقة المستندات التي لا تعد قيمة المعرف الخاصة بها سلسلة (خالية، أو أي نوع بيانات آخر يعتبر غير صالح).

تحديث مجمع للبيانات في حساب Azure Cosmos DB الخاص بك

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

1. انتقل إلى المجلد BulkUpdateSample وافتح ملف BulkUpdateSample.sln .

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

   SetUpdateOperation<string> nameUpdate = new SetUpdateOperation<string>("Name", "UpdatedDoc");
   UnsetUpdateOperation descriptionUpdate = new UnsetUpdateOperation("description");
   
   List<UpdateOperation> updateOperations = new List<UpdateOperation>();
   updateOperations.Add(nameUpdate);
   updateOperations.Add(descriptionUpdate);
   
   List<UpdateItem> updateItems = new List<UpdateItem>();
   for (int i = 0; i < 10; i++)
   {
    updateItems.Add(new UpdateItem(i.ToString(), i.ToString(), updateOperations));
   }
   

3. يستدعي التطبيق واجهة برمجة تطبيقات BulkUpdateAsync . للتعرف على تعريف أسلوب BulkUpdateAsync ، راجع وثائق واجهة برمجة التطبيقات.

   BulkUpdateResponse bulkUpdateResponse = await bulkExecutor.BulkUpdateAsync(
     updateItems: updateItems,
     maxConcurrencyPerPartitionKeyRange: null,
     maxInMemorySortingBatchSize: null,
     cancellationToken: token);
   

   يقبل أسلوب BulkUpdateAsync المعلمات التالية:

   المعلمة‬	الوصف
   maxConcurrencyPerPartitionKeyRange	الحد الأقصى لدرجة التزامن لكل نطاق مفتاح قسم. يؤدي تعيين هذه المعلمة إلى null إلى جعل المكتبة تستخدم القيمة الافتراضية (20).
   maxInMemorySortingBatchSize	تم تمرير الحد الأقصى لعدد عناصر التحديث التي تم سحبها من عداد عناصر التحديث إلى استدعاء واجهة برمجة التطبيقات في كل مرحلة. لمرحلة الفرز في الذاكرة التي تحدث قبل التحديث المجمع. يؤدي تعيين هذه المعلمة إلى قيمة خالية إلى استخدام المكتبة للقيمة الدنيا الافتراضية (updateItems.count، 1000000).
   رمز الإلغاء	رمز الإلغاء للخروج بأمان من عملية التحديث الجماعي.

تعريف كائن استجابة التحديث المجمع
تحتوي نتيجة استدعاء واجهة برمجة التطبيقات للتحديث المجمع على السمات التالية:

المعلمة‬	الوصف
NumberOfDocumentsUpdated (طويل)	عدد المستندات التي تم تحديثها بنجاح من إجمالي المستندات المقدمة لاستدعاء واجهة برمجة التطبيقات للتحديث المجمع.
TotalRequestUnitsConsumed (مزدوج)	إجمالي وحدات الطلب (RUs) التي يستهلكها استدعاء واجهة برمجة التطبيقات للتحديث المجمع.
TotalTimeTaken (TimeSpan)	إجمالي الوقت الذي يستغرقه استدعاء واجهة برمجة التطبيقات للتحديث المجمع لإكمال التنفيذ.

‏‫تلميحات الأداء

ضع في اعتبارك النقاط التالية للحصول على أداء أفضل عند استخدام مكتبة المنفذ المجمع:

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

• يوصى بإنشاء مثيل لكائن BulkExecutor واحد للتطبيق بأكمله داخل جهاز ظاهري واحد يتوافق مع حاوية Azure Cosmos DB معينة.

• يستهلك تنفيذ API لعملية واحدة مجمعة مجموعة كبيرة من وحدة المعالجة المركزية (CPU) الخاصة بجهاز العميل و IO للشبكة عند إنتاج مهام متعددة داخليا. تجنب إنشاء مهام متزامنة متعددة داخل عملية التطبيق الخاصة بك والتي تقوم بتنفيذ استدعاءات واجهة برمجة التطبيقات لعمليات المجموعة. إذا كان استدعاء API لعملية مجمعة واحدة يعمل على جهاز ظاهري واحد غير قادر على استهلاك معدل نقل الحاوية بأكملها (إذا كان معدل نقل > الحاوية الخاصة بك 1 مليون وحدة طلب/ثانية)، فمن المفضل إنشاء أجهزة ظاهرية منفصلة لتنفيذ استدعاءات واجهة برمجة التطبيقات للعملية المجمعة بشكل متزامن.

• تأكد من InitializeAsync() استدعاء الأسلوب بعد إنشاء مثيل كائن BulkExecutor لجلب مخطط قسم حاوية Azure Cosmos DB الهدف.

• في App.Config للتطبيق الخاص بك، تأكد من تمكين gcServer للحصول على أداء أفضل

  <runtime>
    <gcServer enabled="true" />
  </runtime>
  

• تنبعث المكتبة من آثار يمكن جمعها إما في ملف سجل أو على وحدة التحكم. لتمكين كليهما، أضف التعليمات البرمجية التالية إلى ملف App.Config للتطبيق الخاص بك:

  <system.diagnostics>
    <trace autoflush="false" indentsize="4">
      <listeners>
        <add name="logListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="application.log" />
        <add name="consoleListener" type="System.Diagnostics.ConsoleTraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
  

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

• مكتبة المنفذ المجمع ل .NET: معلومات التنزيل (قديم).