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

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

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

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

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

Kotlin

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)

Java

// 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 تُحدِّد عملية التحميل الفعلية:

Kotlin

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

Java

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 لجدولة المهام عند تشغيل تطبيقك على أجهزة لا تتوافق مع JobScheduler (أي الأجهزة التي تعمل بالمستوى 22 من واجهة برمجة التطبيقات أو أقل). وللحصول على التفاصيل الكاملة عن إضافة المكتبات، يُرجى الاطّلاع على بدء استخدام WorkManager.

تعديل البيان

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

تحديد العامل

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

يُحدِّد نموذج رمز GCMNetworkManager مهمة myTask. يبدو ما يعادل WorkManager على النحو التالي:

Kotlin

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()
    }
}

Java

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:

  • تستخدم خدمة رسائل السحابة الإلكترونية من Firebase العنصر 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.

Kotlin

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

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

Java

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 من خلال استدعاء الطريقة المناسبة في كائن أداة الإنشاء للمهمة. على سبيل المثال، يمكنك ضبط متطلبات الشبكة من خلال استدعاء Task.Builder.setRequiredNetwork().

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

قيد GCMNetworkManager مكافئ WorkManager Notes
setPersisted() (غير مطلوب) استمرار جميع مهام WorkManager على مستوى عمليات إعادة تشغيل الجهاز
setRequiredNetwork() setRequiredNetworkType() تتطلب خدمة GCMNetworkManager تلقائيًا الوصول إلى الشبكة. لا يتطلب WorkManager الوصول إلى الشبكة تلقائيًا. إذا كانت وظيفتك تتطلب الوصول إلى الشبكة، يجب استخدام setRequiredNetworkType(CONNECTED) أو ضبط نوع شبكة أكثر تحديدًا.
setRequiresCharging()

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

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

العلامات

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

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

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

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