מעבר מ-GCMNetworkManager ל-WorkManager

במסמך הזה מוסבר איך להעביר אפליקציות לשימוש בספריית הלקוח של WorkManager כדי לבצע פעולות ברקע במקום באמצעות ספריית GCMNetworkManager. הדרך המועדפת לתזמון משימות ברקע היא להשתמש ב-WorkManager. על ידי כולל גם את ספריית WorkManager GCM, אפשר לאפשר ל-WorkManager להשתמש GCM כדי לתזמן את המשימות בעת הרצה במכשירי Android עם רמת API 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 (כלומר, מכשירים עם רמת API 22) או פחות). לקבלת פרטים מלאים על הוספת הספריות, ראו תחילת העבודה עם WorkManager.

שינוי המניפסט

כשהטמעת את GCMNetworkManager, הוספת מופע של GcmTaskService בקובץ המניפסט של האפליקציה, כפי שמתואר בGcmNetworkManager מסמכי עזר. GcmTaskService בודק את המשימה הנכנסת ומעניק אותה למשימה המטפל. ב-WorkManager מנהל את הקצאת המשימות ל-Worker, כך שכבר לא צריכים מחלקה שעושה את זה, פשוט מסירים את GcmTaskService .

הערה: יכול להיות שהוספת לוגיקה ל-GcmTaskService כדי לבצע עבודה כלשהי לפני כן שליחת המשימה ל-handler. במקרה כזה, צריך לבצע ארגון מחדש ולהעביר את הלוגיקה במחלקה Worker שמגדירים בקטע הבא.

הגדרת ה-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 method, כמו 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 מריץ את המשימה ברגע אפשרית אחרי שהמגבלות מתקיימות. בדוגמה הזו, אנחנו מניחים שלא תצטרכו להגדיר זמן ספציפי להרצה של המשימה.

מיפויים של API

בקטע הזה מתואר האופן שבו חלק מהתכונות והאילוצים של GCMNetworkManager ממפים אל שווי ערך ב-WorkManager.

מיפויי מגבלות

GCMNetworkManager מאפשר להגדיר מספר אילוצים הקובעים מתי המשימה צריכה לרוץ. ברוב המקרים יש אילוץ ברור ב-WorkManager. הזה מפרטת את המקבילים האלה.

מגדירים מגבלות במשימות של GCMNetworkManager באמצעות קריאה לשיטה המתאימה אובייקט ה-builder של המשימה. לדוגמה, אפשר להגדיר דרישת רשת כך התקשרות אל Task.Builder.setRequiredNetwork().

ב-WorkManager, אובייקט Constraints.Builder ו קוראים ל-methods של האובייקט כדי להגדיר מגבלות (לדוגמה, Constraints.Builder.setRequiredNetworkType()), להשתמש ב-Builder כדי ליצור אובייקט Constraints (אילוצים), שניתן לצרף בקשת עבודה. מידע נוסף זמין במאמר הגדרת היצירה שלך בקשות.

הערה: ב-GCMNetworkManager אפשר לציין חלון הפעלה ספציפי את המשימה. אין פונקציונליות מקבילה ב-WorkManager. אם צריך פועלות בזמן המדויק. מומלץ להשתמש באפשרויות אחרות, AlarmManager.

אילוץ של GCMNetworkManager	שווה ערך ב-WorkManager	הערות
setPersisted()	(לא חובה)	כל המשימות ב-WorkManager נשמרות בכל ההפעלות מחדש של המכשיר
setRequiredNetwork()	setRequiredNetworkType()	כברירת מחדל, ל-GCMNetworkManager נדרשת גישה לרשת. כברירת מחדל, WorkManager לא מחייב גישה לרשת. אם למשימה נדרשת גישה לרשת, צריך להשתמש ב-setRequiredNetworkType(CONNECTED) או להגדיר סוג רשת ספציפי יותר.
setRequiresCharging()

מיפויים אחרים

מלבד אילוצים, יש הגדרות נוספות שניתן להחיל על GCMNetworkManager למשימות סיווג. בקטע הזה מוצגת הדרך המתאימה להחיל את ההגדרות על משימת WorkManager.

תגים

כל המשימות של GCMNetworkManager חייבות לכלול מחרוזת תג, שאותה ניתן להגדיר באמצעות קריאה setTag() של ה-builder . משימות WorkManager מזוהות באופן ייחודי באמצעות מזהה, נוצר באופן אוטומטי על ידי WorkManager. אפשר לקבל את התעודה המזהה WorkRequest.getId() לחשבון בנוסף, בקשות עבודה יכולות לכלול אופציונלי תג אחד או יותר. כדי להגדיר תג עבור ב-WorkManager, WorkRequest.Builder.addTag() , לפני שמשתמשים ב-builder הזה כדי ליצור את WorkRequest.

ב-GCMNetworkManager ניתן לבצע קריאה setUpdateCurrent() כדי לציין אם המשימה צריכה להחליף כל משימה קיימת באותו תג. הגישה המקבילה ב-WorkManager היא להוסיף למשימה לתור באמצעות קריאה enqueueUniqueWork() או enqueueUniquePeriodicWork(); אם משתמשים בשיטות האלה, נותנים למשימה שם ייחודי, וגם מציינים מנהל העבודה צריך לטפל בבקשה אם כבר יש משימה בהמתנה עם ההגדרה שם. למידע נוסף, ראו טיפול העבודה.

פרמטרים של משימה

ניתן להעביר פרמטרים למשימת GCMNetworkManager באמצעות קריאה Task.Builder.setExtras() ונעביר ערך של Bundle שמכיל את הפרמטרים. WorkManager מאפשר לך להעביר אובייקט Data למשימה של WorkManager, שמכיל את הפרמטרים בתור מפתח/ערך זוגות של מילים. פרטים נוספים זמינים במאמר הקצאת נתוני קלט.