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

مقالة
05/18/2022
قراءة خلال 7 دقائق

ينطبق على: واجهة برمجة تطبيقات SQL

ملاحظة

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

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

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

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

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

إذا لم يكن برنامج Visual Studio 2019 مثبتاً لديك بالفعل، فيمكنك تنزيل واستخدام Visual Studio 2019 Community Edition. تأكد من تمكين "تطوير Azure" أثناء إعداد Visual Studio.
إذا لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانياً قبل أن تبدأ.
يمكنك تجربة Azure Cosmos DB مجاناً دون اشتراك Azure، مجاناً والتزامات. أو يمكنك استخدام Azure Cosmos DB Emulator مع https://localhost:8081نقطة النهاية. يتم توفير المفتاح الأساسي في طلبات المصادقة.
أنشئ حساب واجهة برمجة التطبيقات Azure Cosmos DB SQL باستخدام الخطوات الموضحة في قسم إنشاء حساب قاعدة بيانات في مقالة NET. quickstart.

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

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

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

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

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

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

انتقل إلى مجلد "عينة استيراد المجموعة" وافتح ملف "عينة استيراد المجموعة.sln".

يتم استرداد سلاسل اتصال 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.

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

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

تتم تكوين الكائن 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;

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

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

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

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

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

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

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

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

انتقل إلى مجلد "عينة تحديث المجموعة" وافتح ملف "عينة تحديث المجموعة.sln".
حدد عناصر التحديث جنباً إلى جنب مع عمليات التحديث الميدانية المقابلة. في هذا المثال، ستستخدم 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));
}
```

يستدعي التطبيق واجهة برمجة تطبيقات غير متزامنة لتحديث المجموعة. للتعرف على تعريف طريقة انعدام التزامن لتحديث المجموعة راجع وثائق واجهة برمجة التطبيقات.

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

يقبل أسلوب غير المتزامن لتحديث المجموعة المعلمات التالية:

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

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

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

نصائح حول الأداء

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

للحصول على أفضل أداء، قم بتشغيل التطبيق الخاص بك من جهاز ظاهري Azure موجود في نفس المنطقة مثل منطقة الكتابة لحساب Azure Cosmos الخاص بك.
يوصى بإنشاء مثيل لكائن BulkExecutorواحد للتطبيق بأكمله داخل جهاز ظاهري واحد يتوافق مع حاوية Azure Cosmos معينة.
نظراً لأن تنفيذ واجهة برمجة التطبيقات للعملية المفردة يستهلك جزءاً كبيراً من وحدة المعالجة المركزية لجهاز العميل وشبكة الإدخال / الإخراج (يحدث هذا عن طريق إنتاج مهام متعددة داخلياً). تجنب إنشاء مهام متزامنة متعددة داخل عملية التطبيق الخاصة بك والتي تقوم بتنفيذ استدعاءات واجهة برمجة التطبيقات لعمليات المجموعة. إذا تعذر على استدعاء واجهة برمجة التطبيقات لعملية مجمعة واحدة والذي يتم تشغيله على جهاز ظاهري واحد استهلاك معدل نقل الحاوية بالكامل (إذا كان معدل نقل الحاوية الخاص بك > مليون وحدة طلب/ثانية)، فمن المفضل إنشاء أجهزة ظاهرية منفصلة لتنفيذ عمليات استدعاءات API للعملية المجمعة بشكل متزامن.
تأكد من استدعاء الطريقة InitializeAsync()بعد إنشاء مثيل لكائن BulkExecutor لجلب خريطة قسم حاوية Cosmos الهدف.
في 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>

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

للتعرف على تفاصيل حزمة NuGet وملاحظات الإصدار، راجع تفاصيل حزمة SDK للمنفذ المجمع.