Panduan memulai
mencakup cara membuat
WorkRequest
sederhana dan mengantrekannya.
Dalam panduan ini, Anda akan mempelajari cara menentukan dan menyesuaikan objek WorkRequest
untuk menangani kasus penggunaan umum, seperti cara:
- Menjadwalkan pekerjaan satu kali dan berulang
- Menyetel batasan kerja, seperti perlu menggunakan Wi-Fi atau mengisi daya untuk melakukan pekerjaan
- Menjamin penundaan minimum dalam eksekusi pekerjaan
- Menetapkan strategi percobaan ulang dan back-off
- Meneruskan input data ke pekerjaan
- Mengelompokkan pekerjaan yang saling berkaitan menggunakan tag
Ringkasan
Pekerjaan ditentukan di WorkManager melalui
WorkRequest
. Untuk
menjadwalkan pekerjaan apa pun dengan WorkManager, terlebih dahulu Anda harus membuat objek
WorkRequest
, lalu mengantrekannya.
Kotlin
val myWorkRequest = ... WorkManager.getInstance(myContext).enqueue(myWorkRequest)
Java
WorkRequest myWorkRequest = ... WorkManager.getInstance(myContext).enqueue(myWorkRequest);
Objek WorkRequest berisi semua informasi yang diperlukan oleh WorkManager untuk menjadwalkan dan menjalankan pekerjaan Anda. Ini mencakup batasan yang harus dipenuhi agar pekerjaan dapat dijalankan, penjadwalan informasi seperti penundaan atau interval berulang, konfigurasi percobaan ulang, dan mungkin termasuk menginput data jika pekerjaan membutuhkannya.
WorkRequest
adalah
class dasar abstrak. Ada dua implementasi turunan dari class ini yang
dapat Anda gunakan untuk membuat permintaan,
OneTimeWorkRequest
,
dan
PeriodicWorkRequest
.
Sesuai dengan namanya, OneTimeWorkRequest
berguna untuk menjadwalkan pekerjaan yang tidak berulang,
sementara PeriodicWorkRequest
lebih cocok untuk menjadwalkan
pekerjaan yang berulang pada beberapa interval.
Menjadwalkan pekerjaan satu kali
Untuk pekerjaan sederhana, yang tidak memerlukan konfigurasi tambahan, gunakan
metode statis
from
:
Kotlin
val myWorkRequest = OneTimeWorkRequest.from(MyWork::class.java)
Java
WorkRequest myWorkRequest = OneTimeWorkRequest.from(MyWork.class);
Untuk pekerjaan yang lebih kompleks, Anda dapat menggunakan builder.
Kotlin
val uploadWorkRequest: WorkRequest = OneTimeWorkRequestBuilder<MyWork>() // Additional configuration .build()
Java
WorkRequest uploadWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) // Additional configuration .build();
Menjadwalkan pekerjaan berkala
Terkadang, aplikasi Anda mungkin memerlukan pekerjaan tertentu untuk dijalankan secara berkala. Misalnya, Anda mungkin perlu mencadangkan data, mendownload konten baru di aplikasi, atau mengupload log ke server secara berkala.
Berikut adalah cara menggunakan
PeriodicWorkRequest
untuk membuat objek WorkRequest
yang dieksekusi secara berkala:
Kotlin
val saveRequest = PeriodicWorkRequestBuilder<SaveImageToFileWorker>(1, TimeUnit.HOURS) // Additional configuration .build()
Java
PeriodicWorkRequest saveRequest = new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class, 1, TimeUnit.HOURS) // Constraints .build();
Dalam contoh ini, pekerjaan dijadwalkan dengan interval satu jam.
Periode interval didefinisikan sebagai waktu minimum di antara pengulangan. Waktu pasti eksekusi pekerja bergantung pada batasan yang Anda gunakan dalam objek WorkRequest dan pada pengoptimalan yang dilakukan oleh sistem.
Interval proses fleksibel
Jika sifat pekerjaan Anda sangat bergantung pada waktu eksekusi, Anda dapat mengonfigurasikan
PeriodicWorkRequest
untuk berjalan pada periode fleksibel dalam setiap periode interval, seperti yang ditunjukkan
pada Gambar 1.
Gambar 1. Diagram menunjukkan interval pengulangan dengan periode fleksibel yang dapat digunakan untuk menjalankan pekerjaan.
Untuk menentukan pekerjaan berkala dengan periode flex, Anda perlu meneruskan flexInterval
dengan repeatInterval
saat membuat PeriodicWorkRequest
. Periode flex
dimulai pada repeatInterval - flexInterval
, dan berlanjut ke akhir interval.
Berikut adalah contoh pekerjaan berkala yang dapat dijalankan selama 15 menit terakhir dari setiap periode satu jam.
Kotlin
val myUploadWork = PeriodicWorkRequestBuilder<SaveImageToFileWorker>( 1, TimeUnit.HOURS, // repeatInterval (the period cycle) 15, TimeUnit.MINUTES) // flexInterval .build()
Java
WorkRequest saveRequest = new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class, 1, TimeUnit.HOURS, 15, TimeUnit.MINUTES) .build();
Interval berulang harus lebih besar dari atau sama dengan
PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS
dan interval fleksibel
harus lebih besar dari atau sama dengan
PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS
.
Pengaruh Batasan pada Pekerjaan Berkala
Anda dapat menerapkan batasan untuk pekerjaan berkala. Misalnya,
Anda dapat menambahkan batasan ke permintaan pekerjaan sehingga pekerjaan hanya akan berjalan
saat perangkat pengguna mengisi daya. Dalam kasus ini, meskipun interval
pengulangan yang ditentukan berlalu, PeriodicWorkRequest
tidak akan berjalan sampai kondisi ini
terpenuhi. Hal ini dapat menyebabkan proses tertentu dari pekerjaan Anda menjadi tertunda, atau bahkan
dilewati jika kondisi tidak terpenuhi dalam interval eksekusi.
Batasan pekerjaan
Constraints memastikan bahwa pekerjaan ditangguhkan hingga kondisi optimal terpenuhi. Batasan berikut tersedia untuk WorkManager.
NetworkType | Batasi jenis jaringan yang diperlukan agar pekerjaan Anda dapat berjalan.
Misalnya, Wi-Fi (UNMETERED ).
|
BatteryNotLow | Bila disetel ke benar (true), pekerjaan Anda tidak akan berjalan jika perangkat dalam mode baterai lemah. |
RequiresCharging | Jika disetel ke benar (true), pekerjaan Anda hanya akan berjalan saat perangkat sedang diisi dayanya. |
DeviceIdle | Jika disetel ke benar (true), tindakan ini mengharuskan perangkat pengguna tidak beraktivitas sebelum pekerjaan berjalan. Tindakan ini berguna untuk menjalankan operasi batch yang mungkin berdampak negatif pada performa aplikasi lain yang berjalan secara aktif pada perangkat pengguna. |
StorageNotLow | Jika disetel ke benar (true), pekerjaan Anda tidak akan berjalan jika ruang penyimpanan pengguna di perangkat terlalu rendah. |
Untuk membuat kumpulan batasan dan mengaitkannya ke beberapa pekerjaan, buat instance
Constraints
menggunakan Contraints.Builder()
dan tetapkan ke
WorkRequest.Builder()
.
Misalnya, kode berikut membuat permintaan kerja yang hanya berjalan saat perangkat pengguna mengisi daya dan menggunakan Wi-Fi:
Kotlin
val constraints = Constraints.Builder() .setRequiredNetworkType(NetworkType.UNMETERED) .setRequiresCharging(true) .build() val myWorkRequest: WorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setConstraints(constraints) .build()
Java
Constraints constraints = new Constraints.Builder() .setRequiredNetworkType(NetworkType.UNMETERED) .setRequiresCharging(true) .build(); WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setConstraints(constraints) .build();
Saat beberapa batasan ditentukan, pekerjaan hanya akan berjalan jika semua batasan terpenuhi.
Jika batasan menjadi tidak stabil saat pekerjaan berjalan, WorkManager akan menghentikan pekerja. Pekerjaan tersebut kemudian akan dicoba lagi setelah semua batasan terpenuhi.
Pekerjaan Tertunda
Jika pekerjaan Anda tidak memiliki batasan atau semua batasan terpenuhi saat pekerjaan diantrekan, sistem dapat memilih untuk langsung menjalankan pekerjaan ini. Jika tidak ingin pekerjaan dijalankan langsung, Anda dapat menentukan pekerjaan agar dimulai setelah penundaan awal minimum.
Berikut adalah contoh cara menetapkan pekerjaan agar berjalan minimal 10 menit setelah diantrekan.
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setInitialDelay(10, TimeUnit.MINUTES) .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setInitialDelay(10, TimeUnit.MINUTES) .build();
Meskipun contoh menggambarkan cara menetapkan penundaan awal untuk
OneTimeWorkRequest
, Anda juga dapat menetapkan penundaan awal untuk
PeriodicWorkRequest
. Dalam hal ini, hanya operasi pertama dari pekerjaan berkala Anda
yang akan ditunda.
Kebijakan Percobaan Ulang dan Backoff
Jika Anda mengharuskan WorkManager untuk mencoba kembali pekerjaan, Anda dapat mengembalikan
Result.retry()
dari pekerja. Pekerjaan Anda akan dijadwalkan ulang sesuai dengan penundaan
back-off dan
kebijakan backoff.
Penundaan backoff menentukan jumlah waktu minimum untuk menunggu sebelum mencoba kembali pekerjaan Anda setelah upaya pertama. Nilai ini tidak boleh kurang dari 10 detik (atau MIN_BACKOFF_MILLIS).
Kebijakan backoff menentukan bagaimana keterlambatan backoff akan meningkat dari waktu ke waktu untuk upaya percobaan ulang berikutnya. WorkManager mendukung 2 kebijakan backoff,
LINEAR
danEXPONENTIAL
.
Setiap permintaan pekerjaan memiliki kebijakan backoff dan penundaan backoff. Kebijakan defaultnya
adalah EXPONENTIAL
dengan penundaan selama 10 detik, tetapi Anda dapat menimpanya di
konfigurasi permintaan kerja.
Berikut adalah contoh penyesuaian kebijakan dan penundaan backoff.
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .setBackoffCriteria( BackoffPolicy.LINEAR, OneTimeWorkRequest.MIN_BACKOFF_MILLIS, TimeUnit.MILLISECONDS) .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .setBackoffCriteria( BackoffPolicy.LINEAR, OneTimeWorkRequest.MIN_BACKOFF_MILLIS, TimeUnit.MILLISECONDS) .build();
Dalam contoh ini, penundaan backoff minimum ditetapkan ke nilai minimum yang diizinkan,
10 detik. Karena kebijakannya adalah LINEAR
, interval percobaan ulang akan meningkat
sekitar 10 detik dengan setiap upaya baru. Misalnya, penyelesaian pertama
dengan Result.retry()
akan dicoba lagi setelah 10 detik,
diikuti dengan 20, 30, 40, dan seterusnya, jika pekerjaan terus mengembalikan
Result.retry()
setelah upaya berikutnya. Jika kebijakan backoff ditetapkan ke
EXPONENTIAL
, urutan durasi percobaan ulang akan menjadi lebih dekat ke 20, 40, 80, dan
seterusnya.
Memberi tag pekerjaan
Setiap permintaan pekerjaan memiliki pengenal unik, yang dapat digunakan untuk mengidentifikasi pekerjaan tersebut nanti untuk membatalkan pekerjaan atau mengamati kemajuannya.
Jika memiliki grup pekerjaan yang terkait secara logis, Anda juga dapat membantu untuk memberi tag item kerja tersebut. Pemberian tag memungkinkan Anda untuk beroperasi dengan sekelompok permintaan kerja bersama-sama.
Misalnya,
WorkManager.cancelAllWorkByTag(String)
membatalkan semua Permintaan Kerja dengan tag tertentu, dan
WorkManager.getWorkInfosByTag(String)
menampilkan daftar objek WorkInfo yang dapat digunakan untuk menentukan
status kerja saat ini.
Kode berikut menunjukkan cara menambahkan tag "pembersihan" ke pekerjaan:
Kotlin
val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>() .addTag("cleanup") .build()
Java
WorkRequest myWorkRequest = new OneTimeWorkRequest.Builder(MyWork.class) .addTag("cleanup") .build();
Terakhir, beberapa tag dapat ditambahkan ke satu permintaan pekerjaan. Secara internal, tag ini disimpan sebagai sekumpulan string. Dari permintaan kerja, Anda mengambil kumpulan tag-nya melalui WorkRequest.getTags().
Menetapkan data input
Pekerjaan Anda mungkin memerlukan data input agar dapat melakukan pekerjaannya. Misalnya, pekerjaan yang menangani upload gambar mungkin memerlukan URI gambar untuk diupload sebagai input.
Nilai input disimpan sebagai key-value pair dalam objek
Data
dan dapat ditetapkan pada
permintaan kerja. WorkManager akan mengirimkan input Data
ke tugas Anda saat
menjalankan tugas. Class Worker
dapat mengakses argumen input
dengan memanggil
Worker.getInputData()
.
Kode di bawah ini menunjukkan cara membuat instance Worker
yang memerlukan data input dan cara mengirimkannya dalam permintaan pekerjaan Anda.
Kotlin
// Define the Worker requiring input class UploadWork(appContext: Context, workerParams: WorkerParameters) : Worker(appContext, workerParams) { override fun doWork(): Result { val imageUriInput = inputData.getString("IMAGE_URI") ?: return Result.failure() uploadFile(imageUriInput) return Result.success() } ... } // Create a WorkRequest for your Worker and sending it input val myUploadWork = OneTimeWorkRequestBuilder<UploadWork>() .setInputData(workDataOf( "IMAGE_URI" to "http://..." )) .build()
Java
// Define the Worker requiring input public class UploadWork extends Worker { public UploadWork(Context appContext, WorkerParameters workerParams) { super(appContext, workerParams); } @NonNull @Override public Result doWork() { String imageUriInput = getInputData().getString("IMAGE_URI"); if(imageUriInput == null) { return Result.failure(); } uploadFile(imageUriInput); return Result.success(); } ... } // Create a WorkRequest for your Worker and sending it input WorkRequest myUploadWork = new OneTimeWorkRequest.Builder(UploadWork.class) .setInputData( new Data.Builder() .putString("IMAGE_URI", "http://...") .build() ) .build();
Demikian pula, class Data
dapat digunakan untuk menampilkan nilai hasil. Data input dan
output dibahas secara lebih mendetail di bagian parameter input dan
nilai yang ditampilkan.
Langkah Berikutnya
Di halaman Status dan pengamatan, Anda akan mempelajari lebih lanjut status kerja dan cara memantau progres pekerjaan.