به‌روزرسانی کاری که قبلاً در صف قرار گرفته است

WorkManager به شما امکان می‌دهد WorkRequest را پس‌از اینکه آن را در صف قرار دادید به‌روز کنید. این کار اغلب در برنامه‌های بزرگ‌تر که مکرراً محدودیت‌ها را تغییر می‌دهند یا نیاز دارند کارگران خود را درحال اجرا به‌روز کنند، ضروری است. از WorkManager نسخه ۲.۸.۰، میانای برنامه‌سازی کاربردی updateWork() ابزار انجام این کار است.

روش updateWork() به شما امکان می‌دهد جنبه‌های خاصی از WorkRequest را درحین اجرا تغییر دهید، بدون اینکه لازم باشد فرایند لغو دستی و صف‌بندی مورد جدید را طی کنید. این کار فرایند توسعه را بسیار ساده می‌کند.

اجتناب از لغو کار

به‌طور کلی باید از لغو WorkRequest موجود و صف‌بندی WorkRequest جدید اجتناب کنید. این کار می‌تواند باعث شود برنامه برخی‌از تکالیف را تکرار کند و ممکن است لازم باشد مقدار قابل‌توجهی کد اضافی بنویسید.

نمونه‌های زیر را درنظر بگیرید که در آن‌ها لغو WorkRequest می‌تواند باعث بروز مشکل شود:

  • درخواست پس‌نهایی: اگر Worker را درحالی‌که درحال محاسبه بارداده برای ارسال به سرور است لغو کنید، Worker جدید باید از ابتدا شروع کند و بارداده احتمالاً پرهزینه را دوباره محاسبه کند.
  • زمان‌بندی: اگر PeriodicWorkRequest را لغو کنید و بخواهید PeriodicWorkRequest جدید طبق همان زمان‌بندی اجرا شود، باید انحراف زمانی را محاسبه کنید تا مطمئن شوید زمان اجرای جدید با درخواست کار قبلی مطابقت دارد.

updateWork() API به شما امکان می‌دهد محدودیت‌ها و سایر پارامترهای درخواست کار را بدون دردسر لغو کردن و صف‌بندی درخواست جدید به‌روز کنید.

زمان لغو کار

مواردی وجود دارد که باید مستقیماً WorkRequest را لغو کنید و با updateWork() تماس نگیرید. این کاری است که باید انجام دهید وقتی می‌خواهید ماهیت اساسی کاری را که در صف قرار داده‌اید تغییر دهید.

زمان به‌روزرسانی کار

برنامه عکسی را تصور کنید که روزانه از عکس‌های کاربر پشتیبان‌گیری می‌کند. برای انجام این کار، PeriodicWorkRequest را در صف قرار داده است. WorkRequest محدودیت‌هایی دارد که مستلزم آن است که دستگاه درحال شارژ و به Wi-Fi متصل باشد.

اما کاربر فقط ۲۰ دقیقه در روز دستگاهش را با شارژر سریع شارژ می‌کند. در این حالت، ممکن است برنامه بخواهد WorkRequest را به‌روز کند تا محدودیت شارژ را کاهش دهد، به‌طوری‌که همچنان بتواند عکس‌ها را بارگذاری کند حتی اگر دستگاه کاملاً شارژ نشده باشد.

در این شرایط، می‌توانید از روش updateWork() برای به‌روزرسانی محدودیت‌های درخواست کار استفاده کنید.

نحوه به‌روزرسانی محل کار

روش updateWork() ابزار ساده‌ای برای به‌روزرسانی WorkRequest موجود ارائه می‌دهد، بدون اینکه لازم باشد آن را لغو کنید و در صف جدیدی قرار دهید.

برای استفاده از به‌روزرسانی کار در صف، این مراحل را دنبال کنید:

  1. دریافت شناسه موجود برای کار در صف: شناسه WorkRequest را که می‌خواهید به‌روز کنید دریافت کنید. می‌توانید این شناسه را با هریک از getWorkInfo APIها بازیابی کنید، یا با حفظ دستی شناسه از WorkRequest اولیه برای بازیابی بعدی با ویژگی عمومی WorkRequest.id، قبل‌از قرار دادن آن در صف.
  2. ایجاد WorkRequest جدید: WorkRequest جدیدی ایجاد کنید و از WorkRequest.Builder.setID() استفاده کنید تا شناسه آن را با شناسه WorkRequest موجود مطابقت دهید.
  3. تنظیم محدودیت‌ها: از WorkRequest.Builder.setConstraints() برای ارسال محدودیت‌های جدید WorkManager استفاده کنید.
  4. فراخوانی updateWork: WorkRequest جدید را به updateWork() ارسال کنید.

به‌روزرسانی نمونه کار

در اینجا نمونه تکه‌کدی در Kotlin آورده شده است که نحوه استفاده از روش updateWork() را برای تغییر محدودیت‌های باتری WorkRequest مورداستفاده برای بارگذاری عکس‌ها نشان می‌دهد:

suspend fun updatePhotoUploadWork() {
    // Get instance of WorkManager.
    val workManager = WorkManager.getInstance(context)

    // Retrieve the work request ID. In this example, the work being updated is unique
    // work so we can retrieve the ID using the unique work name.
    val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
        PHOTO_UPLOAD_WORK_NAME
    ).await()

    val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return

    // Update the constraints of the WorkRequest to not require a charging device.
    val newConstraints = Constraints.Builder()
        // Add other constraints as required here.
        .setRequiresCharging(false)
        .build()

    // Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
    val updatedWorkRequest: WorkRequest =
        OneTimeWorkRequestBuilder<MyWorker>()
            .setConstraints(newConstraints)
            .setId(existingWorkRequestId)
            .build()

    // Pass the new WorkRequest to updateWork().
    workManager.updateWork(updatedWorkRequest)
}

مدیریت نتیجه

updateWork() ListenableFuture<UpdateResult> را برمی‌گرداند. UpdateResult ارائه‌شده می‌تواند یکی از چندین مقداری باشد که نشان می‌دهد آیا WorkManager توانسته است تغییرات شما را اعمال کند یا نه. همچنین نشان می‌دهد که چه زمانی توانسته است تغییر را اعمال کند.

برای اطلاعات بیشتر، به مرجع updateWork() و UpdateResult مراجعه کنید.

پیگیری کار با محتوای تولیدشده

هربار که WorkRequest را به‌روز می‌کنید، نسل آن یک عدد افزایش می‌یابد. این به شما امکان می‌دهد دقیقاً ردیابی کنید که کدام WorkRequest درحال‌حاضر در صف قرار دارد. نسل‌ها به شما امکان می‌دهند کنترل بیشتری بر مشاهده، ردیابی، و آزمایش درخواست‌های کاری داشته باشید.

برای دریافت نسل WorkRequest، این مراحل را دنبال کنید:

  1. WorkInfo: برای بازیابی نمونه‌ای از WorkInfo که با WorkRequest شما مطابقت دارد، WorkManager.getWorkInfoById() را فراخوانی کنید.
    • می‌توانید یکی از چندین روشی را که WorkInfo برمی‌گرداند فراخوانی کنید. برای اطلاعات بیشتر، مرجع WorkManager را ببینید.
  2. getGeneration: getGeneration() را در نمونه WorkInfo فراخوانی کنید. ‫Int برگردانده‌شده با تولید WorkRequest مطابقت دارد.
    • توجه داشته باشید که فیلد یا ویژگی تولید وجود ندارد، فقط روش WorkInfo.getGeneration() وجود دارد.

نمونه تولید قطعه موسیقی

در زیر نمونه‌ای از پیاده‌سازی گردش کار شرح‌داده‌شده در بالا برای بازیابی نسل WorkRequest آورده شده است.

// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)

// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)

// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()

خط‌مشی‌های به‌روزرسانی کار

قبلاً، راه‌حل توصیه‌شده برای به‌روزرسانی کار دوره‌ای این بود که PeriodicWorkRequest با خط‌مشی ExistingPeriodicWorkPolicy.REPLACE در صف قرار داده شود. اگر PeriodicWorkRequest معلقی با همان id غیرتکراری وجود داشته باشد، درخواست کار جدید آن را لغو و حذف می‌کند. این خط‌مشی اکنون منسوخ شده است و به‌جای آن از گردش کار بااستفاده از ExistingPeriodicWorkPolicy.UPDATE استفاده می‌شود.

برای مثال، هنگام استفاده از enqueueUniquePeriodicWork با PeriodicWorkRequest، می‌توانید PeriodicWorkRequest جدید را با خط‌مشی ExistingPeriodicWorkPolicy.UPDATE مقداردهی اولیه کنید. اگر PeriodicWorkRequest معلقی با همان نام غیرتکراری وجود داشته باشد، WorkManager آن را به مشخصات جدید به‌روز می‌کند. با دنبال کردن این گردش کار، نیازی به استفاده از updateWork() نیست.