النقل من GCMNetworkManager إلى WorkManager

يشرح هذا المستند كيفية نقل التطبيقات لاستخدام مكتبة برامج WorkManager. إجراء العمليات في الخلفية بدلاً من مكتبة GCMNetworkManager. تشير رسالة الأشكال البيانية أن يكون استخدام تطبيق WorkManager هو الطريقة المفضلة لجدولة المهام في الخلفية. من بما في ذلك أيضًا مكتبة WorkManager GCM، يمكنك تمكين WorkManager لاستخدام GCM لجدولة المهام عند تشغيلها على أجهزة Android التي تعمل بالمستوى 22 من واجهة برمجة التطبيقات أو أقل.

نقل البيانات إلى WorkManager

إذا كان تطبيقك يستخدم حاليًا GCMNetworkManager لإجراء العمليات في الخلفية، اتّبِع الخطوات التالية للترحيل إلى WorkManager.

بالنسبة للخطوات التالية، نفترض أنك تبدأ بما يلي رمز GCMNetworkManager، الذي يحدد مهمتك ويجدولها:

val myTask = OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService::class.java)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(5 * DateUtil.MINUTE_IN_SECONDS,
            15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build()
GcmNetworkManager.getInstance(this).schedule(myTask)

// In GcmNetworkManager, this call defines the task and its
// runtime constraints:
OneoffTask myTask = new OneoffTask.Builder()
    // setService() says what class does the work
    .setService(MyUploadService.class)
    // Don't run the task unless device is charging
    .setRequiresCharging(true)
    // Run the task between 5 & 15 minutes from now
    .setExecutionWindow(
        5 * DateUtil.MINUTE_IN_SECONDS,
        15 * DateUtil.MINUTE_IN_SECONDS)
    // Define a unique tag for the task
    .setTag("test-upload")
    // ...finally, build the task and assign its value to myTask
    .build();
GcmNetworkManager.getInstance(this).schedule(myTask);

في هذا المثال، نفترض أنّ السمة MyUploadService تحدّد عملية التحميل الفعلية:

class MyUploadService : GcmTaskService() {
    fun onRunTask(params: TaskParams): Int {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS
    }
}

class MyUploadService extends GcmTaskService {
    @Override
    public int onRunTask(TaskParams params) {
        // Do some upload work
        return GcmNetworkManager.RESULT_SUCCESS;
    }
}

تضمين مكتبات WorkManager

لاستخدام صفوف WorkManager، يجب إضافة مكتبة WorkManager إلى وبناء التبعيات. يجب أيضًا إضافة مكتبة WorkManager GCM، التي يمكّن WorkManager من استخدام GCM لجدولة المهام عند تشغيل التطبيق الأجهزة التي لا تتوافق مع Job Scheduler (أي الأجهزة التي تعمل بالمستوى 22 من واجهة برمجة التطبيقات) أو أقل). للحصول على التفاصيل الكاملة حول إضافة المكتبات، راجع الخطوات الأولى لاستخدام WorkManager:

تعديل البيان

عند تنفيذ GCMNetworkManager، أضفت مثيلاً GcmTaskService إلى بيان التطبيق، كما هو موضّح في GcmNetworkManager المستندات المرجعية ينظر "GcmTaskService" إلى المهمة الواردة ويفوّضها إليها . يدير WorkManager تفويض المهام للعاملين، لذلك لا يمكنك بحاجة إلى فئة تقوم بذلك؛ ما عليك سوى إزالة GcmTaskService من البيان.

تعريف العامل

يحدِّد تنفيذ GCMNetworkManager OneoffTask أو RecurringTask، والذي يحدد فقط العمل الذي يجب القيام به. أنت بحاجة إلى إعادة كتابة ذلك Worker، على النحو الموثق في تعريف عملك الطلبات.

يحتوي نموذج GCMNetworkManager الرمز تحدد مهمة myTask. يبدو مكافئ WorkManager كما يلي:

class UploadWorker(context: Context, params: WorkerParameters)
                        : Worker(context, params) {
    override fun doWork() : Result {
        // Do the upload operation ...
        myUploadOperation()

        // Indicate whether the task finished successfully with the Result
        return Result.success()
    }
}

public class UploadWorker extends Worker {

    public UploadWorker(
        @NonNull Context context,
        @NonNull WorkerParameters params) {
        super(context, params);
    }

    @Override
    public Result doWork() {
      // Do the upload operation ...

      myUploadOperation()

      // Indicate whether the task finished successfully with the Result
      return Result.success()
    }
}

هناك بعض الاختلافات بين مهمة GCM وWorker:

• تستخدم خدمة GCM الكائن TaskParams لتمرير المعلمات إلى المهمة. تشير رسالة الأشكال البيانية يستخدم WorkManager بيانات الإدخال، التي يمكنك تحديدها في WorkRequest، كما هو موضح في مستندات WorkManager الخاصة بتعريف الإدخال/الإخراج مهمتك. وفي كلتا الحالتين، يمكنك تمرير أزواج المفتاح/القيمة لتحديد أي أزواج قابلة للإبقاء المعاملات التي تحتاجها المهمة.
• تشير GcmTaskService إلى النجاح أو الفشل من خلال عرض علامات مثل GcmNetworkManager.RESULT_SUCCESS يشير Worker WorkManager إلى نتائجه باستخدام ListenableWorker.Result مثل ListenableWorker.Result.success(), وإرجاع القيمة المعروضة لتلك الطريقة.
• وكما ذكرنا سابقًا، لا يمكنك وضع قيود أو علامات عند تحديد Worker؛ بدلاً من ذلك، يمكنك القيام بذلك في الخطوة التالية، عند إنشاء WorkRequest

جدولة طلب العمل

عند تحديد Worker، ما يجب تنفيذه. لتحديد وقت العمل ينبغي القيام به، فأنت بحاجة إلى تحديد WorkRequest:

1. إنشاء OneTimeWorkRequest أو PeriodicWorkRequest، تعيين أي قيود مطلوبة لتحديد وقت تشغيل المهمة، وكذلك وأي علامات لتحديد عملك.
2. تمرير الطلب إلى WorkManager.enqueue() لوضع المهمة في قائمة الانتظار للتنفيذ.

على سبيل المثال، أظهر القسم السابق كيفية تحويل OneoffTask إلى Worker مكافئ. ومع ذلك، لم يتم تضمين Worker في قيود تنفيذ الكائن OneoffTask والعلامة. بدلاً من ذلك، نضع ومعرّف المهمة عند إنشاء WorkRequest. سنحدد أيضًا أنّه يجب عدم تشغيل المهمّة ما لم يكن هناك اتصال بالشبكة. لا تحتاج إلى لطلب اتصال بالشبكة بشكل صريح مع GCMNetworkManager، نظرًا يتطلب GCMNetworkManager اتصالاً بالشبكة تلقائيًا، لكن WorkManager يفعله اتصالاً بالشبكة ما لم تضف هذا القيد على وجه التحديد. بعد تعريف WorkRequest، ندرجه في قائمة انتظار مع WorkManager.

val uploadConstraints = Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true).build()

val uploadTask = OneTimeWorkRequestBuilder<UploadWorker>()
    .setConstraints(uploadConstraints)
    .build()
WorkManager.getInstance().enqueue(uploadTask)

Constraints uploadConstraints = new Constraints.Builder()
    .setRequiredNetworkType(NetworkType.CONNECTED)
    .setRequiresCharging(true)
    .build();

OneTimeWorkRequest uploadTask =
        new OneTimeWorkRequest.Builder(UploadWorker.class)
  .setConstraints(uploadConstraints)
  .build();
WorkManager.getInstance().enqueue(uploadTask);

عمليات ربط واجهة برمجة التطبيقات

يصف هذا القسم كيفية ربط بعض ميزات وقيود GCMNetworkManager على ما يعادلها من WorkManager.

عمليات ربط التقييد

يتيح لك GCMNetworkManager تعيين عدد من القيود حول موعد مهمتك الجري. في معظم الحالات، هناك قيد WorkManager مكافئ واضح. هذا النمط هذه المكافئات.

تعيين قيود على مهام GCMNetworkManager من خلال استدعاء الطريقة المناسبة في كائن Builder بالمهمة؛ على سبيل المثال، يمكنك تعيين متطلبات الشبكة عن طريق يَتِمُّ الْآنَ الِاتِّصَالْ بِـ Task.Builder.setRequiredNetwork().

في WorkManager، يمكنك إنشاء الكائن Constraints.Builder و طرق هذا الكائن لضبط القيود (على سبيل المثال، Constraints.Builder.setRequiredNetworkType()), ثم استخدام أداة Builder لإنشاء كائن القيود الذي يمكنك إرفاقه مع طلب العمل. لمزيد من المعلومات، راجع تحديد عملك الطلبات.

عمليات الربط الأخرى

بالإضافة إلى القيود، هناك إعدادات أخرى يمكنك تطبيقها على GCMNetworkManager المهام. يسرد هذا القسم الطريقة المتوافقة لتطبيق هذه الإعدادات على وظيفة مدير العمل.

العلامات

يجب أن تحتوي جميع مهام GCMNetworkManager على سلسلة علامة يمكنك ضبطها عن طريق استدعاء setTag() للمنشئ . يتم تحديد وظائف WorkManager بشكل فريد عن طريق المعرف، وهو تم إنشاؤها تلقائيًا بواسطة WorkManager؛ فيمكنك الحصول على هذا المعرّف من خلال الاتصال WorkRequest.getId() ضِمن بالإضافة إلى ذلك، يمكن أن تحتوي طلبات العمل اختياريًا على علامة واحدة أو أكثر. لتحديد علامة لوظيفة مدير العمل، عليك باستدعاء WorkRequest.Builder.addTag() قبل استخدام أداة الإنشاء لإنشاء WorkRequest.

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

مَعلمات المهام

يمكنك تمرير المعلمات إلى مهمة GCMNetworkManager من خلال استدعاء Task.Builder.setExtras() وتمرير Bundle يحتوي على المعلَمات. يسمح لك WorkManager باجتياز كائن Data إلى مهمة WorkManager، تحتوي على المعلَمات على أنّها مفتاح/قيمة أزواج. للحصول على التفاصيل، يمكنك مراجعة تخصيص بيانات الإدخال: