Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Menentukan permintaan pekerjaan

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.

Anda dapat menyetel interval fleksibel untuk tugas berkala. Anda menentukan interval pengulangan, dan interval fleksibel yang menentukan jumlah waktu tertentu di akhir interval pengulangan. WorkManager mencoba menjalankan pekerjaan Anda pada waktu tertentu selama interval flex pada setiap siklus.

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 dan EXPONENTIAL.

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.