أفضل الممارسات لأداة NET. SDK لـ Azure Cosmos DB

ينطبق على: NoSQL

تستعرض هذه المقالة أفضل الممارسات لاستخدام أداة NET. SDK لـ Azure Cosmos DB. باتباع هذه الممارسات، سيساعدك في تحسين زمن الانتقال والتوفر وتعزيز الأداء الكلي.

شاهد الفيديو أدناه لمعرفة المزيد حول استخدام .NET SDK من مهندس Azure Cosmos DB!

قائمة تدقيق

محدد	الموضوع	التفاصيل/الارتباطات
	إصدار SDK	استخدم دائما أحدث إصدار من Azure Cosmos DB SDK المتاح للحصول على الأداء الأمثل.
	عميل قاعدة بيانات أحادية	استخدم مثيلاً واحداً لـ CosmosClient طوال فترة عمل تطبيقك للحصول على أفضل أداء.
	المناطق	تأكد من تشغيل تطبيقك في منطقة Azure نفسها الموجودة في حساب Azure Cosmos DB، لتقليل زمن الانتقال إن أمكن ذلك. مكِّن منطقتين إلى 4 مناطق وانسخ حساباتك في مناطق متعددة للحصول على أفضل إمكانية توافر. بالنسبة لأحمال عمل الإنتاج، قم بتمكين تجاوز الفشل المدار بواسطة الخدمة. في حالة عدم وجود هذا التكوين، سيواجه الحساب فقدان إمكانية الكتابة طوال مدة انقطاع منطقة الكتابة، حيث لن ينجح تجاوز الفشل اليدوي بسبب نقص اتصال المنطقة. لمعرفة كيفية إضافة مناطق متعددة باستخدام NET. SDK تفضّل بزيارة هنا
	التوفر وتجاوز الفشل	قم بتعيين ApplicationPreferredRegions أو ApplicationRegion في الإصدار 3 SDK، وPreferredLocations في v2 SDK باستخدام قائمة المناطق المفضلة. أثناء تجاوز الفشل، تُرسَل عمليات الكتابة إلى منطقة الكتابة الحالية وتُرسَل عمليات القراءة إلى المنطقة الأولى ضمن قائمة المناطق المفضلة. لمزيد من المعلومات حول آليات تجاوز الفشل الإقليمية، راجع دليل تحري الخلل وإصلاحه في التوفر.
	معالج	قد تواجه مشكلات في الاتصال/التوفر بسبب عدم وجود موارد على جهاز العميل. راقب استخدام CPU الخاص بك على العقد التي تقوم بتشغيل عميل Azure Cosmos DB، وقم بزيادة / زيادة الاستخدام إذا كان الاستخدام مرتفعاً.
	الاستضافة	استخدم معالجة المضيف 64 بت في Windows للحصول على أفضل أداء، كلما أمكن ذلك. بالنسبة لأحمال عمل الإنتاج الحساسة لزمن الانتقال المباشر، نوصي بشدة باستخدام 4 ذاكرات أساسية على الأقل وأجهزة ظاهرية للذاكرة بسعة 8 غيغابايت كلما أمكن ذلك.
	أوضاع الاتصال	استخدم الوضع المباشر للحصول على أفضل أداء. للحصول على تعليمات عن كيفية القيام بذلك، راجع وثائق SDK V3 أو وثائق SDK V2.
	الشبكات	في حالة استخدام جهاز ظاهري لتشغيل التطبيق، مكِّن الشبكات المتسارعة على الجهاز الظاهري للمساعدة في تخفيف الازدحامات بسبب ارتفاع نسبة استخدام الشبكة وتقليل زمن الانتقال أو توتر وحدة المعالجة المركزية. قد ترغب أيضاً في النظر في استخدام جهاز ظاهري بنهاية عالية حيث يبلغ الحد الأقصى لاستخدام وحدة المعالجة المركزية أقل من 70%.
	استهلاك المنفذ المؤقت	للاتصالات المتفرقة أو المتقطعة، نعيِّنIdleConnectionTimeout وPortReuseMode على PrivatePortPool. IdleConnectionTimeout تساعد الخاصية في التحكم في الوقت الذي يتم بعده إغلاق الاتصالات غير المستخدمة. وهذا يقلل من عدد الاتصالات غير المستخدمة. ستظل الاتصالات الساكنة مفتوحة إلى أجل غير مسمى افتراضياً. يجب أن تكون مجموعة القيمة أكبر من 10 دقائق أو مساوية لها. نوصي باستخدام قيم بين 20 دقية و24 ساعة. تسمح الخاصية PortReuseMode لأداة SDK باستخدام تجمع صغير من المنافذ المؤقتة لنقاط نهاية وجهة Azure Cosmos DB مختلفة.
	استخدام غير متزامن/الانتظار	تجنب حظر الاستدعاءات: Task.Result وTask.Wait وTask.GetAwaiter().GetResult(). مكدس الاستدعاءات بأكمله غير متزامن للاستفادة من أنماط غير متزامن/الانتظار. تؤدي العديد من الاستدعاءات المحظورة المتزامنة إلى نقص تجمع مؤشر الترابط وانخفاض أداء أوقات الاستجابة.
	المهلات الشاملة	للحصول على المهلات من طرف إلى طرف، تحتاج إلى استخدام كل من RequestTimeout المعلمات و CancellationToken . لمزيد من التفاصيل ، تفضل بزيارة دليل استكشاف أخطاء المهلة وإصلاحها.
	منطق إعادة المحاولة	لمزيد من المعلومات حول الأخطاء التي يجب إعادة المحاولة عليها وتلك التي تتم إعادة محاولة تنفيذها بواسطة SDKs، راجع دليل التصميم. بالنسبة للحسابات التي تم تكوينها مع مناطق متعددة، هناك بعض السيناريوهات حيث سيعيد SDK المحاولة تلقائيا على مناطق أخرى. للحصول على تفاصيل التنفيذ الخاصة ب .NET، تفضل بزيارة مستودع مصدر SDK.
	التخزين المؤقت لقاعدة البيانات/أسماء المجموعات	استرد أسماء قواعد البيانات والحاويات من التكوين أو خزِّنها مؤقتاً في البداية. ستؤدي المكالمات مثل ReadDatabaseAsync أو ReadDocumentCollectionAsync وCreateDatabaseQuery أو CreateDocumentCollectionQuery إلى استدعاءات بيانات التعريف للخدمة، والتي تستهلك من حد RU المحجوز من قِبل النظام. يجب استخدام CreateIfNotExist أيضاً مرة واحدة لإعداد قاعدة البيانات فقط. عامة ينبغي تنفيذ هذه العمليات بشكل غير منتظم.
	الدعم المجمع	في السيناريوهات التي قد لا تحتاج فيها إلى تحسين زمن الانتقال، نوصي بتمكين الدعم المجمع لنسخ كميات كبيرة من البيانات احتياطياً.
	استعلامات متوازية	يدعم Azure Cosmos DB SDK تشغيل الاستعلامات بالتوازي للحصول على زمن انتقال ومعدل نقل أفضل على استعلاماتك. نوصي بتعيين الخاصية MaxConcurrency ضمن QueryRequestsOptions إلى عدد الأقسام لديك. إذا لم تكن على علم بعدد الأقسام، فابدأ باستخدام int.MaxValue، والذي سيمنحك أفضل زمن انتقال. ثم قلِّل الرقم إلى أن يناسب قيود موارد البيئة لتجنب حدوث مشكلات CPU عالية. أيضا، قم بتعيين MaxBufferedItemCount إلى العدد المتوقع من النتائج التي تم إرجاعها للحد من عدد النتائج مسبقة الجلب.
	التراجع عن اختبار الأداء	عند إجراء الاختبار على التطبيق الخاص بك، يجب عليك تنفيذ فترات التراجع على فترات زمنية تبلغ RetryAfter. يساعد احترام التراجع على ضمان قضاء الحد الأدنى من الوقت في الانتظار بين عمليات إعادة المحاولة.
	الفهرسة	يسمح لك نهج الفهرسة من Azure Cosmos DB أيضاً بتحديد مسارات المستند المطلوب تضمينها أو استبعادها من الفهرسة باستخدام مسارات الفهرسة (IndexingPolicy.IncludedPaths وIndexingPolicy.ExcludedPaths). تأكد من استبعاد المسارات غير المستخدمة من الفهرسة للكتابة بشكل أسرع. لمزيد من المعلومات حول كيفية إنشاء فهارس باستخدام SDK، راجع نصائح الأداء .NET SDK v3.
	حجم المستند	يرتبط رسم الطلب لعملية محددة بحجم المستند مباشرة. نوصي بتقليل حجم المستندات حيث تكلف العمليات التي تُجرى على المستندات الكبيرة مبلغاً أكبر من العمليات التي تُجرى على المستندات الأصغر.
	زيادة عدد مؤشرات الترابط/المهام	نظراً لإجراء الاستدعاءات لـ Azure Cosmos DB عبر الشبكة، قد تحتاج إلى تغيير درجة تزامن طلباتك بحيث ينتظر تطبيق العميل أدنى فترة ممكنة بين الطلبات. على سبيل المثال، إذا كنت تستخدم مكتبة متوازية لمهام NET.، فأنشئ طلباً بعدد كبير من المهام التي تُقرأ أو تُكتَب على Azure Cosmos DB.
	تمكين قياسات الاستعلام	لمزيد من تسجيل عمليات تنفيذ استعلام الواجهة الخلفية، يمكنك تمكين SQL Query Metrics باستخدام .NET SDK. لمزيد من المعلومات حول كيفية جمع مقاييس استعلام SQL، راجع مقاييس الاستعلام والأداء.
	تسجيل SDK	تسجيل تشخيصات SDK للسيناريوهات المعلقة، مثل الاستثناءات أو عندما تتجاوز الطلبات زمن الانتقال المتوقع.
	DefaultTraceListener	يطرح DefaultTraceListener مشكلات الأداء على بيئات التشغيل ما يسبب ازدحامات عالية في CPU والإدخال/إخراج. تأكد من أنك تستخدم أحدث إصدارات SDK أو أزل DefaultTraceListener من تطبيقك
	تجنب استخدام أي أحرف خاصة في المعرفات	بعض الأحرف مقيدة ولا يمكن استخدامها في بعض المعرفات: '/'، '\'، '?'، '#'. التوصية العامة هي عدم استخدام أي أحرف خاصة في المعرفات مثل اسم قاعدة البيانات أو اسم المجموعة أو معرف العنصر أو مفتاح القسم لتجنب أي سلوك غير متوقع.

تسجيل التشخيص

تتضمن جميع الاستجابات في SDK على CosmosExceptionخاصية التشخيصDiagnostics. تسجل هذه الخاصية كل المعلومات الخاصة بالطلب المفرد بما في ذلك إذا كانت هناك إعادة محاولة أو أي فشل مؤقت.

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

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

أفضل الممارسات لاتصالات HTTP

يستخدم HttpClient .NET SDK لتنفيذ طلبات HTTP بغض النظر عن وضع الاتصال الذي تم تكوينه. في الوضع المباشر ، يتم استخدام HTTP لعمليات بيانات التعريف وفي وضع البوابة، يتم استخدامه لكل من عمليات مستوى البيانات وبيانات التعريف. أحد أساسيات HttpClient هو التأكد من إمكانية HttpClient التفاعل مع تغييرات DNS على حسابك عن طريق تخصيص مدة بقاء الاتصال المجمع. طالما يتم الاحتفاظ بالاتصالات المجمعة مفتوحة، فإنها لا تتفاعل مع تغييرات DNS. يفرض هذا الإعداد إغلاق الاتصالات المجمعة بشكل دوري، ما يضمن تفاعل تطبيقك مع تغييرات DNS. توصيتنا هي أن تقوم بتخصيص هذه القيمة وفقا لوضع الاتصال وعبء العمل الخاص بك لموازنة تأثير الأداء لإنشاء اتصالات جديدة بشكل متكرر، مع الحاجة إلى التفاعل مع تغييرات DNS (التوفر). ستكون قيمة 5 دقائق بداية جيدة يمكن زيادتها إذا كانت تؤثر على الأداء خاصة في وضع البوابة.

يمكنك إدخال HttpClient المخصص من خلال CosmosClientOptions.HttpClientFactory، على سبيل المثال:

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

إذا كنت تستخدم إدخال تبعية .NET، يمكنك تبسيط عملية Singleton:

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

أفضل الممارسات عند استخدام وضع البوابة

زد System.Net MaxConnections لكل مضيف عند استخدام وضع البوابة. تُجرى طلبات DB Cosmos Azure عبر HTTPS/REST عند استخدام وضع البوابة. تلتزم بحد الاتصال الافتراضي لكل اسم مضيف، أو عنوان IP. قد تحتاج إلى تعيين MaxConnections إلى قيمة أعلى (من 100 إلى 1000) بحيث يمكن أن تستخدم مكتبة العميل اتصالات متزامنة متعددة لـ Azure Cosmos DB. في NET. SDK 1.8.0 والإصدوائر الأحدث، تكون القيمة الافتراضية لـ ServicePointManager.DefaultConnectionLimit 50. لتغيير القيمة، يمكنك تعيين CosmosClientOptions.GatewayModeMaxConnectionLimit على قيمة أعلى.

أفضل الممارسات لعمليات سير العمل المليئة بالكتابة

بالنسبة لعمليات سير العمل التي تحتوي على أعباء إنشاء كبيرة، عيِّن خيار الطلب EnableContentResponseOnWrite على false. لن تعيد الخدمة المورد المُكوَن أو المُحدَث إلى SDK بعد الآن. عادة بسبب احتواء التطبيق على الكائن المُكوَن، لن يحتاج إلى الخدمة لإعادته. لا يزال الوصول إلى قيم العنوان ممكناً مثل رسوم الطلب. يمكن أن يساعد تعطيل استجابة المحتوى في تحسين الأداء، لأن SDK لا تحتاج إلى تخصيص الذاكرة أو تحديد تسلسل نص الاستجابة بعد الآن. يقلل أيضاً استخدام النطاق الترددي للشبكة للمساعدة في الحصول على أفضل أداء.

هام

سيؤدي الإعداد EnableContentResponseOnWrite إلى أيضا إلى false تعطيل الاستجابة من عملية مشغل.

أفضل الممارسات للتطبيقات متعددة المستأجرين

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

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

يوصى في هذه الحالات ب:

• فهم قيود بيئة الحوسبة (وحدة المعالجة المركزية وموارد الاتصال). نوصي باستخدام الأجهزة الظاهرية مع 4 ذاكرات أساسية على الأقل وذاكرة 8 غيغابايت كلما أمكن ذلك.
• استنادا إلى قيود بيئة الحساب، حدد عدد مثيلات العميل (وبالتالي عدد المستأجرين) التي يمكن لمثيل حساب واحد التعامل معها. يمكنك تقدير عدد الاتصالات التي سيتم فتحها لكل عميل اعتمادا على وضع الاتصال المختار.
• تقييم توزيع المستأجر عبر المثيلات. إذا كان كل مثيل حساب يمكنه التعامل بنجاح مع كمية محدودة معينة من المستأجرين، فإن موازنة التحميل وتوجيه المستأجرين إلى مثيلات حساب مختلفة سيسمح بالتحجيم مع زيادة عدد المستأجرين.
• بالنسبة لأحمال العمل المتفرقة، ضع في اعتبارك استخدام ذاكرة التخزين المؤقت الأقل استخداما كبنية للاحتفاظ بمثيلات العميل والتخلص من العملاء للمستأجرين الذين لم يتم الوصول إليها خلال نافذة زمنية. أحد الخيارات في .NET هو MemoryCacheEntryOptions، حيث يمكن استخدام RegisterPostEvictionCallbackللتخلص من العملاء غير النشطين ويمكن استخدام SetSlidingExpiration لتحديد الحد الأقصى للوقت للاحتفاظ بالاتصالات غير النشطة.
• تقييم استخدام وضع البوابة لتقليل عدد اتصالات الشبكة.
• عند استخدام الوضع المباشر ، ضع في اعتبارك ضبط CosmosClientOptions.IdleTcpConnectionTimeoutوCosmosClientOptions.PortReuseMode على تكوين الوضع المباشر لإغلاق الاتصالات غير المستخدمة والحفاظ على حجم الاتصالات تحت التحكم.

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

للحصول على نموذج تطبيق يُستخدم لتقييم Azure Cosmos DB للسيناريوهات عالية الأداء على عدد قليل من أجهزة العميل، راجع اختبار الأداء والقياس باستخدام Azure Cosmos DB.

لمعرفة المزيد حول تصميم تطبيقك بحيث يتناسب مع الحجم والأداء العالي، راجع التقسيم والقياس في Azure Cosmos DB.

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

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