تسلسل الأعمال

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

لإنشاء سلسلة من المهام، يمكنك استخدام WorkManager.beginWith(OneTimeWorkRequest) أو WorkManager.beginWith(List<OneTimeWorkRequest>) ، حيث يعرض كل منهما مثيلاً من WorkContinuation.

يمكن بعد ذلك استخدام WorkContinuation لإضافة مثيلات OneTimeWorkRequest تابعة باستخدام then(OneTimeWorkRequest) أو then(List<OneTimeWorkRequest>).

يؤدي كل استدعاء لـ WorkContinuation.then(...) إلى عرض مثيل جديد من WorkContinuation. إذا أضفت List من مثيلات OneTimeWorkRequest، يمكن تشغيل هذه الطلبات بالتوازي.

أخيرًا، يمكنك استخدام الطريقة WorkContinuation.enqueue() لـ enqueue() سلسلة WorkContinuation.

لنلقِ نظرة على أحد الأمثلة. في هذا المثال، تم ضبط 3 مهام مختلفة لـ Worker ليتم تشغيلها (ربما بالتوازي). بعد ذلك، يتم دمج نتائج هذه العمال وتمريرها إلى مهمة عامل التخزين المؤقت. أخيرًا، يتم تمرير مخرجات هذه المهمة إلى عامل تحميل، والذي يقوم بتحميل النتائج إلى خادم بعيد.

Kotlin

WorkManager.getInstance(myContext)
   // Candidates to run in parallel
   .beginWith(listOf(plantName1, plantName2, plantName3))
   // Dependent work (only runs after all previous work in chain)
   .then(cache)
   .then(upload)
   // Call enqueue to kick things off
   .enqueue()

Java

WorkManager.getInstance(myContext)
   // Candidates to run in parallel
   .beginWith(Arrays.asList(plantName1, plantName2, plantName3))
   // Dependent work (only runs after all previous work in chain)
   .then(cache)
   .then(upload)
   // Call enqueue to kick things off
   .enqueue();

عمليات الدمج الواردة

عند ربط مثيلات OneTimeWorkRequest، يتم تمرير ناتج طلبات العمل الرئيسية كمدخلات إلى الطلبات الفرعية. في المثال أعلاه، سيتم تمرير مخرجات plantName1 وplantName2 وplantName3 كمدخلات لطلب cache.

لإدارة المدخلات من طلبات عمل رئيسية متعددة، يستخدم WorkManager InputMerger.

هناك نوعان مختلفان من InputMerger يوفّرهما WorkManager:

  • OverwritingInputMerger يحاول إضافة جميع المفاتيح من جميع المدخلات إلى المخرجات. في حال حدوث تعارضات، يتم استبدال المفاتيح التي تم ضبطها سابقًا.

  • ArrayCreatingInputMerger يحاول دمج المدخلات، وإنشاء مصفوفات عند الضرورة.

إذا كانت لديك حالة استخدام أكثر تحديدًا، يمكنك كتابة الحالة الخاصة بك عن طريق إنشاء فئة فرعية من InputMerger.

OverwritingInputMerger

‫OverwritingInputMerger هي طريقة الدمج التلقائية. إذا كانت هناك تعارضات في المفاتيح في عملية الدمج، فستحل أحدث قيمة للمفتاح محل أي إصدارات سابقة في بيانات الإخراج الناتجة.

على سبيل المثال، إذا كان لكل من مدخلات المصنع مفتاح يطابق أسماء المتغيرات الخاصة به ("plantName1" و"plantName2" و"plantName3")، فإن البيانات التي يتم تمريرها إلى العامل cache ستحتوي على ثلاثة أزواج من المفاتيح والقيم.

مخطّط بياني يعرض ثلاث مهام تمرّر مخرجات مختلفة إلى المهمة التالية في السلسلة. بما أنّ المخرجات الثلاثة تحتوي جميعها على مفاتيح مختلفة، تتلقّى المهمة التالية ثلاثة أزواج من المفاتيح والقيم.

في حال حدوث تعارض، فإنّ آخر عامل يكمل المهمة "يفوز"، ويتم تمرير قيمته إلى cache.

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

بما أنّ طلبات العمل يتم تنفيذها بالتوازي، لا يمكننا ضمان ترتيب تنفيذها. في المثال أعلاه، يمكن أن يحمل plantName1 قيمة "tulip" أو "elm"، بناءً على القيمة التي تمت كتابتها أخيرًا. إذا كان هناك احتمال لحدوث تعارض في المفاتيح وكنت بحاجة إلى الاحتفاظ بجميع بيانات المخرجات في عملية دمج، فقد يكون ArrayCreatingInputMerger خيارًا أفضل.

ArrayCreatingInputMerger

في المثال أعلاه، بما أنّنا نريد الاحتفاظ بالمخرجات من جميع عمال أسماء النباتات، علينا استخدام ArrayCreatingInputMerger.

Kotlin

val cache: OneTimeWorkRequest = OneTimeWorkRequestBuilder<PlantWorker>()
   .setInputMerger(ArrayCreatingInputMerger::class)
   .setConstraints(constraints)
   .build()

Java

OneTimeWorkRequest cache = new OneTimeWorkRequest.Builder(PlantWorker.class)
       .setInputMerger(ArrayCreatingInputMerger.class)
       .setConstraints(constraints)
       .build();

يربط ArrayCreatingInputMerger كل مفتاح بمصفوفة. إذا كان كل مفتاح فريدًا، ستكون النتيجة سلسلة من المصفوفات التي تحتوي على عنصر واحد.

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

في حال حدوث أي تعارضات في المفاتيح، يتم تجميع أي قيم مقابلة معًا في مصفوفة.

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

حالات الربط والعمل

يتم تنفيذ سلاسل OneTimeWorkRequest بشكل تسلسلي طالما أنّ عملها يكتمل بنجاح (أي أنّها تعرض Result.success()). قد يتعذّر تنفيذ طلبات العمل أو يتم إلغاؤها أثناء التشغيل، ما يؤدي إلى تأثيرات لاحقة على طلبات العمل التابعة.

عندما تتم إضافة أول OneTimeWorkRequest إلى قائمة الانتظار في سلسلة من طلبات العمل، يتم حظر جميع طلبات العمل اللاحقة إلى أن يكتمل عمل طلب العمل الأول.

مخطّط بياني يعرض سلسلة من الوظائف تتم إضافة المهمة الأولى إلى قائمة الانتظار، ويتم حظر جميع المهام المتتالية إلى أن تنتهي المهمة الأولى.

بعد إضافة طلبات العمل إلى قائمة الانتظار واستيفاء جميع قيود العمل، يبدأ تنفيذ طلب العمل الأول. إذا تم إكمال العمل بنجاح في الجذر OneTimeWorkRequest أو List<OneTimeWorkRequest> (أي أنّه يعرض Result.success())، سيتم وضع المجموعة التالية من طلبات العمل التابعة في قائمة الانتظار.

مخطّط بياني يعرض سلسلة من الوظائف نجحت المهمة الأولى، وتمت إضافة المهمتَين التاليتَين لها مباشرةً إلى قائمة الانتظار. يتم حظر المهام المتبقية حتى تنتهي المهام السابقة.

طالما أنّ كل طلب عمل يكتمل بنجاح، يتم نشر هذا النمط نفسه من خلال بقية سلسلة طلبات العمل حتى يكتمل كل العمل في السلسلة. على الرغم من أنّ هذه هي الحالة الأبسط والمفضّلة غالبًا، فإنّ معالجة حالات الخطأ لا تقل أهمية.

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

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

لمزيد من المعلومات حول تحديد استراتيجيات إعادة المحاولة المخصّصة، يُرجى الاطّلاع على سياسة إعادة المحاولة والتراجع.

إذا كانت سياسة إعادة المحاولة غير محدّدة أو تم استنفادها، أو إذا وصلت إلى حالة تؤدي فيها OneTimeWorkRequest إلى عرض Result.failure()، يتم وضع علامة FAILED. على طلب العمل هذا وجميع طلبات العمل التابعة له.

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

ينطبق المنطق نفسه عند إلغاء OneTimeWorkRequest. يتم أيضًا وضع علامة CANCELLED على أي طلبات عمل تابعة ولن يتم تنفيذها.

مخطّط بياني يعرض سلسلة من الوظائف تم إلغاء مهمة واحدة. نتيجةً لذلك، يتم أيضًا إلغاء جميع المهام التي تليها في السلسلة.

يُرجى العِلم أنّه في حال إلحاق المزيد من طلبات العمل بسلسلة تتضمّن طلبات عمل تعذّر تنفيذها أو تم إلغاؤها، سيتم أيضًا وضع علامة FAILED أو CANCELLED على طلب العمل المُلحَق حديثًا، على التوالي. إذا أردت تمديد عمل سلسلة حالية، يمكنك الاطّلاع على APPEND_OR_REPLACE في ExistingWorkPolicy.

عند إنشاء سلاسل من طلبات العمل، يجب أن تحدّد طلبات العمل التابعة سياسات إعادة المحاولة لضمان إكمال العمل دائمًا في الوقت المناسب. قد تؤدي طلبات العمل التي تعذّر تنفيذها إلى سلاسل غير مكتملة و/أو حالة غير متوقعة.

لمزيد من المعلومات، يُرجى الاطّلاع على إلغاء العمل وإيقافه.