مشاركة عبر

ضبط تكوينات الاتصال ل Azure Cosmos DB Java SDK v4

  • مقالة

ينطبق على: NoSQL

هام

تلميحات الأداء الواردة في هذه المقالة خاصة بـ Azure Cosmos DB Java SDK v4 فقط. الرجاء عرض Azure Cosmos DB Java SDK v4 ملحوظات الإصدار ومستودع Maven وAzure Cosmos DB Java SDK v4 دليل استكشاف الأخطاء وإصلاحها لمزيد من المعلومات. إذا كنت تستخدم حاليّاً إصداراً أقدم من الإصدار 4، فراجع دليل الترحيل إلى حزمة تطوير برامج Java Azure Cosmos DB - الإصدار 4 للمساعدة على الترقية إلى الإصدار 4.

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

تكوين الاتصال

إشعار

في Azure Cosmos DB Java SDK v4، يعد الوضع المباشر هو الخيار الأفضل لتحسين أداء قاعدة البيانات مع معظم أحمال العمل.

لمعرفة مزيد حول خيارات الاتصال المختلفة، راجع مقالة أوضاع الاتصال.

وضع الاتصال المباشر

وضع الاتصال الظاهري Java SDK مباشر. يتم إجراء طلبات Azure Cosmos DB في الوضع المباشر عبر TCP عند استخدام Azure Cosmos DB Java SDK v4. يستخدم الوضع المباشر الداخلي بنية خاصة لإدارة موارد الشبكة ديناميكيًّا، والحصول على أفضل أداء. تتيح بنية جانب العميل المستخدمة في الوضع المباشر الاستخدام المتوقع للشبكة والوصول المتعدد إلى النسخ المتماثلة لـAzure Cosmos DB. لمعرفة المزيد حول البنية، راجع بنية اتصال الوضع المباشر

يمكنك تكوين وضع الاتصال في منشئ العميل باستخدام أسلوب directMode() كما هو موضح أدناه. لتكوين الوضع المباشر مع الإعدادات الافتراضية، قم باستدعاء directMode() الأسلوب بدون وسيطات. لتخصيص إعدادات اتصال الوضع المباشر، مرر DirectConnectionConfig إلى directMode() API.

Java SDK V4 (Maven com.azure::azure-cosmos) Async API


/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildAsyncClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildAsyncClient();

/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildAsyncClient();

/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildAsyncClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildAsyncClient();

تخصيص وضع الاتصال المباشر

إذا كان سلوك الوضع المباشر غير الظاهري مطلوباً، فأنشئ مثيل DirectConnectionConfig وخصص خصائصه، ثم مرر مثيل الخاصية المخصص إلى طريقة directMode () في منشئ عميل Azure Cosmos DB .

تتحكم إعدادات التكوين هذه في سلوك بنية الوضع المباشر الأساسية التي تمت مناقشتها أعلاه.

كخطوة أولى، استخدم إعدادات التكوين الموصى بها أدناه. تُعد خيارات DirectConnectionConfig هذه إعدادات تكوين متقدمة يمكن أن تؤثر في أداء SDK بطرق غير متوقعة؛ نوصي المستخدمين بتجنب تعديلها ما لم يشعروا براحة كبيرة في فهم المفاضلات، وكان ذلك ضروريًّا للغاية. الرجاء الاتصال بفريق Azure Cosmos DB إذا واجهت مشكلات في هذا الموضوع المحدد.

خيار التكوين الإعداد الافتراضي مستحسن التفاصيل
idleConnectionTimeout "PT0" (صفر) "PT0" (صفر) يمثل هذا مدة مهلة الاتصال الخامل لاتصال واحد بنقطة نهاية/ عقدة خلفية (تمثل نسخة متماثلة). بشكل افتراضي، لا تغلق SDK تلقائيا الاتصالات الخاملة لعقد الواجهة الخلفية.
idleEndpointTimeout "PT1H" "PT1H" يمثل هذا مدة مهلة الاتصال الخاملة لتجمع الاتصال لعقدة نقطة نهاية/خلفية (تمثل نسخة متماثلة). بشكل افتراضي، إذا لم تكن هناك طلبات واردة إلى نقطة نهاية/ عقدة خلفية معينة، فستغلق SDK جميع الاتصالات في تجمع الاتصال إلى نقطة النهاية/ عقدة الخلفية هذه بعد ساعة واحدة لحفظ موارد الشبكة وتكلفة الإدخال/الإخراج. بالنسبة لنمط نسبة استخدام الشبكة المتفرق أو المتقطع، نوصي بتعيين هذه القيمة إلى رقم أعلى مثل 6 ساعات أو 12 ساعة أو حتى 24 ساعة، بحيث لا تضطر SDK إلى فتح الاتصالات بشكل متكرر. ومع ذلك، سيستخدم هذا موارد الشبكة وسيكون له عدد أكبر من الاتصالات التي يتم الاحتفاظ بها مفتوحة في أي وقت. إذا تم تعيين هذا إلى ZERO، تعطيل التحقق من نقطة النهاية الخاملة.
maxConnectionsPerEndpoint "130" "130" يمثل هذا الحجم الحد الأعلى لتجمع الاتصال لنقطة نهاية/ عقدة خلفية (تمثل نسخة متماثلة). ينشئ SDK اتصالات بنقطة النهاية/ عقدة الخلفية عند الطلب واستنادا إلى الطلبات المتزامنة الواردة. بشكل افتراضي، إذا لزم الأمر، ستنشئ SDK 130 اتصالا كحد أقصى إلى نقطة نهاية/ عقدة خلفية. (ملاحظة: لا تقوم SDK بإنشاء هذه الاتصالات ال 130 مقدما).
maxRequestsPerConnection "30" "30" يمثل هذا الحجم العلوي الحد الأقصى لعدد الطلبات التي يمكن وضعها في قائمة الانتظار على اتصال واحد لنقطة نهاية معينة/ عقدة خلفية (تمثل نسخة متماثلة). تقوم SDK بقوائم انتظار الطلبات إلى اتصال واحد بنقطة نهاية/ عقدة خلفية عند الطلب واستنادا إلى الطلبات المتزامنة الواردة. بشكل افتراضي، إذا لزم الأمر، ستقوم SDK بقائمة انتظار 30 طلبا كحد أقصى لاتصال واحد لنقطة نهاية معينة/ عقدة خلفية. (ملاحظة: لا تقوم SDK بقائمة انتظار هذه الطلبات الثلاثين إلى اتصال واحد مقدما).
connectTimeout "PT5S" "~PT1S" يمثل هذا مدة مهلة إنشاء الاتصال لاتصال واحد ليتم إنشاؤه مع نقطة نهاية / عقدة خلفية. بشكل افتراضي، ستنتظر SDK لمدة 5 ثوان كحد أقصى لإنشاء الاتصال قبل طرح خطأ. تستخدم مؤسسة اتصال TCP تأكيد اتصال متعدد الخطوات مما يزيد من زمن انتقال وقت إنشاء الاتصال، ومن ثم، يوصى العملاء بتعيين هذه القيمة وفقا لعرض النطاق الترددي للشبكة وإعدادات البيئة الخاصة بهم. ملاحظة: هذه التوصية من ~PT1S مخصصة فقط للتطبيقات التي تم نشرها في المناطق المجمعة لحسابات Cosmos DB الخاصة بها.
وقت طلب الشبكة "PT5S" "PT5S" يمثل هذا مدة مهلة الشبكة لطلب واحد. ستنتظر SDK الحد الأقصى لهذه المدة لاستهلاك استجابة خدمة بعد كتابة الطلب إلى اتصال الشبكة. يسمح SDK فقط بالقيم بين ثانية واحدة (دقيقة) و10 ثوان (الحد الأقصى). يمكن أن يؤدي تعيين قيمة عالية جدا إلى عدد أقل من عمليات إعادة المحاولة وتقليل فرص النجاح عن طريق إعادة المحاولة.

وضع اتصال البوابة

تستخدم عمليات وحدة التحكم مثل قاعدة البيانات والحاويات CRUD دائما وضع البوابة. حتى عندما يكون المستخدم قد قام بتكوين الوضع المباشر لعمليات مستوى البيانات، تستخدم وحدة التحكم وعمليات بيانات التعريف إعدادات وضع البوابة الافتراضية. هذا يناسب معظم المستخدمين. ومع ذلك، يمكن للمستخدمين الذين يريدون الوضع المباشر لعمليات مستوى البيانات، بالإضافة إلى ضبط معلمات وضع البوابة لمستوى التحكم استخدام تجاوز directMode () التالي:

Java SDK V4 (Maven com.azure::azure-cosmos) Async API


/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

تخصيص وضع اتصال البوابة

إذا كان سلوك وضع البوابة غير الافتراضي مطلوبا، فأنشئ مثيل GatewayConnectionConfig وخصص خصائصه، ثم مرر مثيل الخاصية المخصصة إلى أسلوب تجاوز directMode() أعلاه أو أسلوب gatewayMode() في منشئ عميل Azure Cosmos DB.

كخطوة أولى، استخدم إعدادات التكوين الموصى بها أدناه. خيارات GatewayConnectionConfig هذه هي إعدادات تكوين متقدمة يمكن أن تؤثر على أداء SDK بطرق غير متوقعة؛ نوصي المستخدمين بتجنب تعديلها ما لم يشعروا بالراحة الشديدة في فهم المقايضات وهو أمر ضروري للغاية. الرجاء الاتصال بفريق Azure Cosmos DB إذا واجهت مشكلات في هذا الموضوع المحدد.

خيار التكوين الإعداد الافتراضي مستحسن التفاصيل
maxConnectionPoolSize "1000" "1000" يمثل هذا الحجم الحد الأعلى لحجم تجمع الاتصال لعميل http الأساسي، وهو الحد الأقصى لعدد الاتصالات التي ستقوم SDK بإنشائها للطلبات التي تنتقل إلى وضع البوابة. تعيد SDK استخدام هذه الاتصالات عند إرسال الطلبات إلى البوابة.
idleConnectionTimeout "PT60S" "PT60S" يمثل هذا مدة مهلة الاتصال الخامل لاتصال واحد بالبوابة. بعد هذا الوقت، سيتم إغلاق الاتصال تلقائيا وستتم إزالته من تجمع الاتصال.

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

لمعرفة المزيد حول نصائح الأداء لـ Java SDK، راجع تلميحات الأداء لـ Azure Cosmos DB Java SDK الإصدار رقم 4.

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

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