مشاركة عبر

قم بإنشاء استعلامات لسرد موارد Batch بكفاءة

  • مقالة

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

إشعار

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

تحديد مستوى التفاصيل

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

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

// Get a collection of all of the tasks and all of their properties for job-001
IPagedEnumerable<CloudTask> allTasks =
    batchClient.JobOperations.ListTasks("job-001");

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

// Configure an ODATADetailLevel specifying a subset of tasks and
// their properties to return
ODATADetailLevel detailLevel = new ODATADetailLevel();
detailLevel.FilterClause = "state eq 'completed'";
detailLevel.SelectClause = "id,commandLine,nodeInfo";

// Supply the ODATADetailLevel to the ListTasks method
IPagedEnumerable<CloudTask> completedTasks =
    batchClient.JobOperations.ListTasks("job-001", detailLevel);

في هذا السيناريو المثال، إذا كان هناك آلاف المهام في الوظيفة، فإن النتائج من الاستعلام الثاني عادةً ما يتم إرجاعها بسرعة أكبر من الاستعلام الأول. لمزيد من المعلومات حول استخدام ODATADetailLevel عند إدراج العناصر باستخدام واجهة برمجة التطبيقات من Batch .NET، راجع قسم الاستعلام الفعال في Batch .NET.

هام

نوصي بشدة أن تقوم دائمًا بتوفير عنصر ODATADetailLevel لاستدعاءات قائمة واجهة برمجة التطبيقات من .NET لتحقيق أقصى قدر من الكفاءة والأداء لتطبيقك. من خلال تحديد مستوى التفاصيل، يمكنك المساعدة في تقليل أوقات استجابة خدمة الدُفعة، وتحسين استخدام الشبكة، وتقليل استخدام الذاكرة من قِبل تطبيقات العميل.

استخدم سلاسل الاستعلام

يمكنك استخدام واجهات برمجة تطبيقات Batch .NET وBatch REST لتقليل عدد العناصر التي يرجعها الاستعلام، ومقدار المعلومات التي يرجعها الاستعلام لكل عنصر. يوجد ثلاثة أنواع من سلاسل طلبات البحث يمكنك استخدامها لتضييق نطاق طلب البحث: $ filter و$ select و$ expand.

لمعرفة المزيد حول واجهة برمجة التطبيقات لدى Batch .NET، راجع خصائص فئة ODATADetailLevel. راجع أيضًا قسم الاستعلام الفعال في Batch .NET.

لمعرفة المزيد حول واجهة برمجة تطبيقات من Batch REST، راجع مرجع واجهة برمجة تطبيقات Batch REST. ابحث عن مرجع القائمة للمورد الذي تريد الاستعلام عنه. ثم راجع قسم معلمات URI للحصول على تفاصيل حول $filter و$select و$expand. على سبيل المثال، راجع معلمات URI ل Pool - List. راجع أيضًا كيفية إجراء استعلامات Batch فعالة باستخدام Azure CLI.

إشعار

عند إنشاء أي من أنواع سلاسل الاستعلام الثلاثة، يجب أن تتأكد من تطابق أسماء الخاصية والحالة مع نظرائهم من عناصر واجهة برمجة تطبيقات REST. على سبيل المثال، عند العمل مع فئة .NET‏ CloudTask، يجب عليك تحديد state بدلاً من State، على الرغم من أن الخاصية .NET هي CloudTask.State. لمزيد من المعلومات، راجع تعيينات الخصائص بين واجهات برمجة تطبيقات .NET وREST.

عامل التصفية

تقلل سلسلة التعبير $filter من عدد العناصر التي يتم إرجاعها. على سبيل المثال، يمكنك فقط سرد المهام الجارية لوظيفة ما، أو سرد عُقد الحوسبة الجاهزة فقط لتشغيل المهام.

تتكون هذه السلسلة من تعبير واحد أو أكثر، مع تعبير يتكون من اسم الخاصية وعامل التشغيل والقيمة. الخصائص التي يمكن تحديدها هي خاصة بكل نوع كيان تقوم بالاستعلام عنه، وكذلك عوامل التشغيل المعتمدة لكل خاصية. يمكن دمج تعبيرات متعددة باستخدام عوامل التشغيل المنطقية and وor.

يسرد هذا المثال مهام العرض الجارية فحسب: (state eq 'running') and startswith(id, 'renderTask').

حدد

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

يحدد هذا المثال أنه يجب إرجاع ثلاث قيم خصائص لكل مهمة فحسب: id, state, stateTransitionTime.

توسيع

تقلل سلسلة التعبير $expand من عدد استدعاءات واجهة برمجة التطبيقات المطلوبة للحصول على معلومات معينة. يمكنك استخدام هذه السلسلة للحصول على مزيد من المعلومات حول كل عنصر باستخدام استدعاء واجهة برمجة تطبيقات واحدة. يساعد هذا الأسلوب على تحسين الأداء عن طريق تقليل استدعاءات واجهة برمجة التطبيقات. استخدم سلسلة $expand بدلاً من الحصول على قائمة الكيانات وطلب معلومات حول كل عنصر قائمة.

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

تتضمن الاستخدامات المدعومة لهذه السلسلة سرد الوظائف وجداول الوظائف والمهام والتجمعات. وهي لا تدعم حاليًا سوى معلومات الإحصائيات فقط.

يحدد هذا المثال أنه يجب إرجاع معلومات الإحصائيات لكل عنصر في القائمة: stats.

قواعد التصفية وسلاسل التحديد والتوسيع

  • تأكد من ظهور أسماء الخصائص في سلاسل التصفية والتحديد والتوسيع كما تظهر في واجهة برمجة تطبيقات Batch REST. تنطبق هذه القاعدة حتى عند استخدام Batch .NET أو أحد حزم SDK الأخرى.
  • جميع أسماء الخصائص حساسة لحالة الأحرف، لكن قيم الخصائص غير حساسة لحالة الأحرف.
  • يمكن أن تكون سلاسل التاريخ / الوقت أحد التنسيقين، ويجب أن تُسبق بـ DateTime.
    • مثال على تنسيق W3C-DTF: creationTime gt DateTime'2011-05-08T08:49:37Z'
    • مثال على تنسيق RFC 1123: creationTime gt DateTime'Sun, 08 May 2011 08:49:37 GMT'
  • السلاسل المنطقية هي إما true أو false.
  • إذا حُددت خاصية أو عامل غير صالح، فسيظهر خطأ 400 (Bad Request).

الاستعلام الفعال في الدُفعة .NET

في واجهة برمجة تطبيقات Batch .NET، توفر فئة ODATADetailLevel تصفية، وتحديد، وتوسيع السلاسل لسرد العمليات . الفئة ODataDetailLevel لها ثلاث خصائص سلسلة عامة. يمكنك تحديد هذه الخصائص في الدالة الإنشائية، أو تعيين الخصائص مباشرةً على الكائن. بعد ذلك، قم بتمرير الكائن ODataDetailLevel كمعامل لعمليات القائمة المتنوعة مثل ListPools وListJobs وListTasks.

  • ODATADetailLevel.FilterClause: تحديد عدد العناصر التي يتم إرجاعها.
  • ODATADetailLevel.SelectClause: تحديد قيم الخصائص التي يتم إرجاعها مع كل عنصر.
  • ODATADetailLevel.ExpandClause: استرداد البيانات لجميع العناصر في استدعاء واحد لواجهة برمجة التطبيقات للنظام بدلاً من استدعاءات منفصلة لكل عنصر.

تستخدم القصاصة البرمجية التالية واجهة برمجة التطبيقات من Batch .NET للاستعلام عن خدمة Batch بكفاءة من أجل إحصائيات مجموعة معينة من التجمعات. مستخدم Batch لديه مجمعات اختبار وإنتاج. مُعرّفات تجمع الاختبار مسبوقة بـ "اختبار" ومُعرّفات تجمع الإنتاج مسبوقة بـ "prod". myBatchClient هو مثيل تمت تهيئته بشكل صحيح لفئة BatchClient.

// First we need an ODATADetailLevel instance on which to set the filter, select,
// and expand clause strings
ODATADetailLevel detailLevel = new ODATADetailLevel();

// We want to pull only the "test" pools, so we limit the number of items returned
// by using a FilterClause and specifying that the pool IDs must start with "test"
detailLevel.FilterClause = "startswith(id, 'test')";

// To further limit the data that crosses the wire, configure the SelectClause to
// limit the properties that are returned on each CloudPool object to only
// CloudPool.Id and CloudPool.Statistics
detailLevel.SelectClause = "id, stats";

// Specify the ExpandClause so that the .NET API pulls the statistics for the
// CloudPools in a single underlying REST API call. Note that we use the pool's
// REST API element name "stats" here as opposed to "Statistics" as it appears in
// the .NET API (CloudPool.Statistics)
detailLevel.ExpandClause = "stats";

// Now get our collection of pools, minimizing the amount of data that is returned
// by specifying the detail level that we configured above
List<CloudPool> testPools =
    await myBatchClient.PoolOperations.ListPools(detailLevel).ToListAsync();

تلميح

يمكن أيضاً تمرير مثيل ODATADetailLevel الذي كُوّن باستخدام عبارات "تحديد وتوسيع" إلى أساليب "الحصول" المناسبة، مثل PoolOperations.GetPool، للحد من كمية البيانات التي يتم إرجاعها.

دُفعة REST لتعيينات واجهة برمجة تطبيقات .NET

يجب أن تعكس أسماء الخصائص الخاصة بسلاسل التصفية والتحديد والتوسيع نظيراتها في واجهة برمجة تطبيقات REST الخاصة بهم، سواء في الاسم أو الحالة. توفر الجداول أدناه تعيينات بين النظيرين .NET وواجهة برمجة تطبيقات REST.

تعيينات سلاسل التصفية

  • أساليب سرد .NET : تقبل كل طريقة من أساليب واجهة برمجة التطبيقات .NET في هذا العمود كائن ODATADetailLevel كمُعامل.
  • طلبات قائمة REST: تحتوي كل صفحة واجهة برمجة تطبيقات REST مدرجة في هذا العمود على جدول بالخصائص والعمليات المسموح بها في سلاسل التصفية. يمكنك استخدام أسماء الخصائص والعمليات هذه عند إنشاء سلسلة ODATADetailLevel.FilterClause.
أساليب سرد .NET طلبات سرد REST
CertificateOperations.ListCertificates سرد الشهادات في حساب
CloudTask.ListNodeFiles سرد الملفات المقترنة بمهمة
JobOperations.ListJobPreparationAndReleaseTaskStatus سرد حالة مهام إعداد الوظيفة وإصدار الوظيفة لمهمة ما
JobOperations.ListJobs سرد الوظائف في حساب
JobOperations.ListNodeFiles سرد الملفات الموجودة في عقدة
JobOperations.ListTasks سرد الملفات المقترنة بمهمة
JobScheduleOperations.ListJobSchedules سرد جداول الوظائف في حساب
JobScheduleOperations.ListJobs سرد الوظائف المقترنة بجدول مهام
PoolOperations.ListComputeNodes سرد عُقد الحوسبة في تجمع
PoolOperations.ListPools سرد التجمعات في حساب

تعيينات سلاسل التحديد

  • أنواع الدُفعة .NET: أنواع واجهة برمجة التطبيقات للدُفعات .NET.
  • كيانات واجهة برمجة تطبيقات REST: تحتوي كل صفحة في هذا العمود على جدول واحد أو أكثر يسرد أسماء خصائص واجهة برمجة تطبيقات REST للنوع. تُستخدم أسماء الخصائص هذه عند إنشاء سلاسل التحديد. يمكنك استخدام نفس أسماء الخصائص هذه عند إنشاء سلسلة ODATADetailLevel.SelectClause.
أنواع دُفعة .NET كيانات واجهة برمجة تطبيقات REST
شهادة الحصول على معلومات حول شهادة
CloudJob الحصول على معلومات حول وظيفة
CloudJobSchedule الحصول على معلومات حول جدول وظيفة
عُقد الحوسبة الحصول على معلومات حول عقدة
CloudPool الحصول على معلومات حول تجمع
CloudTask الحصول على معلومات حول مهمة

مثال: إنشاء سلسلة عوامل تصفية

لإنشاء سلسلة تصفية لـ ODATADetailLevel.FilterClause، ابحث عن صفحة واجهة برمجة تطبيقات REST المقابلة. الخصائص القابلة للتحديد وعوامل التشغيل المدعومة موجودة في أول جدول متعدد الصفوف. على سبيل المثال، لاسترداد جميع المهام التي كان رمز الخروج فيها غير صفري، حدد List the tasks associated with a job لسلسلة الخاصية القابلة للتطبيق وعوامل التشغيل المسموح بها:

الخاصية العمليات المسموح بها نوع
executionInfo/exitCode eq, ge, gt, le , lt Int

سلسلة التصفية ذات الصلة هي:

(executionInfo/exitCode lt 0) or (executionInfo/exitCode gt 0)

مثال: إنشاء سلسلة تحديد

إنشاء ODATADetailLevel.SelectClause، ابحث عن صفحة واجهة برمجة تطبيقات REST المقابلة للكيان الذي تقوم بإدراجه. الخصائص القابلة للتحديد وعوامل التشغيل المدعومة موجودة في أول جدول متعدد الصفوف. على سبيل المثال، لاسترداد المعرف وسطر الأوامر فقط لكل مهمة في القائمة، افحص الحصول على معلومات حول مهمة:

الخاصية نوع ملاحظات
id String The ID of the task.
commandLine String The command line of the task.

سلسلة التحديد ذات الصلة هي:

id, commandLine

نماذج التعليمات البرمجية

استعلامات قائمة فعالة

يوضح مشروع نموذج EfficientListQueries مدى فعالية استعلام القائمة في التأثير على أداء التطبيق. ينشئ تطبيق وحدة التحكم C # ويضيف عدداً كبيراً من المهام إلى الوظيفة. بعد ذلك، يقوم التطبيق بإجراء استدعاءات متعددة إلى أسلوب JobOperations.ListTasks ويمرر كائنات ODATADetailLevel. يتم تكوين هذه الكائنات بقيم خصائص مختلفة لتغيير مقدار البيانات التي سيتم إرجاعها. تنتج هذه العينة إخراجًا مشابهًا لما يلي:

Adding 5000 tasks to job jobEffQuery...
5000 tasks added in 00:00:47.3467587, hit ENTER to query tasks...

4943 tasks retrieved in 00:00:04.3408081 (ExpandClause:  | FilterClause: state eq 'active' | SelectClause: id,state)
0 tasks retrieved in 00:00:00.2662920 (ExpandClause:  | FilterClause: state eq 'running' | SelectClause: id,state)
59 tasks retrieved in 00:00:00.3337760 (ExpandClause:  | FilterClause: state eq 'completed' | SelectClause: id,state)
5000 tasks retrieved in 00:00:04.1429881 (ExpandClause:  | FilterClause:  | SelectClause: id,state)
5000 tasks retrieved in 00:00:15.1016127 (ExpandClause:  | FilterClause:  | SelectClause: id,state,environmentSettings)
5000 tasks retrieved in 00:00:17.0548145 (ExpandClause: stats | FilterClause:  | SelectClause: )

Sample complete, hit ENTER to continue...

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

مكتبة BatchMetrics

يوضح نموذج مشروع BatchMetrics التالي كيفية مراقبة تقدم مهمة Azure Batch بكفاءة باستخدام واجهة برمجة التطبيقات الدفعة.

يتضمن هذا النموذج مشروع مكتبة فئة .NET، والذي يمكنك دمجه في مشاريعك الخاصة. يوجد أيضًا برنامج سطر أوامر بسيط لممارسة وإثبات استخدام المكتبة.

يوضح نموذج التطبيق داخل المشروع هذه العمليات:

  • تحديد سمات معينة لتنزيل الخصائص التي تحتاجها فحسب
  • التصفية في أوقات انتقال الحالة لتنزيل التغييرات فقط منذ الاستعلام الأخير

على سبيل المثال، يظهر الأسلوب التالي في مكتبة BatchMetrics. يقوم بإرجاع ODATADetailLevel الذي يحدد أنه يجب الحصول على الخصائص id وstate فقط للكيانات التي يتم الاستعلام عنها. كما تحدد أيضاً أنه يجب إرجاع الكيانات التي تغيرت حالتها فقط منذ المُعامل DateTime المحدد.

internal static ODATADetailLevel OnlyChangedAfter(DateTime time)
{
    return new ODATADetailLevel(
        selectClause: "id, state",
        filterClause: string.Format("stateTransitionTime gt DateTime'{0:o}'", time)
    );
}

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