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

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

تعديل البيان

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

ملاحظة: ربما تكون قد أضفت منطقًا إلى GcmTaskService لتنفيذ بعض الإجراءات قبل إرسال المهمة إلى المعالج. في هذه الحالة، تحتاج إلى إعادة هيكلة الجهاز هذا المنطق في فئة Worker التي تحددها في القسم التالي.

تعريف العامل

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

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

يحتوي نموذج 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:

• تستخدم خدمة 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.

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 هي معرّف WorkRequest. يتم ضبط هذا المعرّف تلقائيًا من قبل WorkManager عند إنشاء الطلب؛ تحصل على المعرّف عن طريق الاتصال WorkRequest.getId() مدير العمل يسمح لك أيضًا بتحديد علامات لوظائفك، ولكنها تختلف عن علامات GCMNetworkManager لأنّه لا يجب أن تكون فريدة قد يكون لديك العديد من تتم إضافة مهام WorkManager المشابهة إلى قائمة الانتظار في وقت واحد، وجميعها باستخدام العلامة نفسها.

ملاحظة: يتطلب GCMNetworkManager تحديد نافذة تنفيذ، ولكن لا يتطلب WorkManager هذا. بدلاً من ذلك، يدير WorkManager المهمة بمجرد ممكن بعد تلبية القيود. في هذا المثال، نفترض أنك لا إلى تحديد وقت محدد لتنفيذ المهمة.

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

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

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

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

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

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

ملاحظة: يتيح لك GCMNetworkManager تحديد نافذة تنفيذ معينة مهمتك. لا تتوفّر وظائف مكافئة في WorkManager. إذا كنت بحاجة إلى تعمل في الوقت المحدد، ننصحك باستخدام خيارات أخرى، مثل AlarmManager.

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

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

بالإضافة إلى القيود، هناك إعدادات أخرى يمكنك تطبيقها على 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، تحتوي على المعلَمات على أنّها مفتاح/قيمة أزواج. للحصول على التفاصيل، يمكنك مراجعة تخصيص بيانات الإدخال: