Xác định yêu cầu công việc

Phần hướng dẫn bắt đầu sử dụng đã chỉ cho bạn cách tạo một WorkRequest đơn giản và thêm yêu cầu đó vào hàng đợi.

Trong phần hướng dẫn này, bạn sẽ tìm hiểu cách xác định và tuỳ chỉnh các đối tượng WorkRequest để xử lý các trường hợp sử dụng phổ biến, chẳng hạn như cách:

• Lên lịch công việc định kỳ và công việc một lần
• Thiết lập các điều kiện ràng buộc công việc, chẳng hạn như yêu cầu Wi-Fi hoặc sạc
• Đảm bảo độ trễ tối thiểu trong quá trình thực thi công việc
• Thiết lập các chiến lược thời gian đợi và thử lại
• Truyền dữ liệu đầu vào để làm việc
• Nhóm các công việc liên quan cùng nhau bằng thẻ

Tổng quan

Công việc được xác định trong WorkManager qua một WorkRequest. Để lên lịch công việc với WorkManager, trước tiên, bạn phải tạo một đối tượng WorkRequest rồi thêm đối tượng này vào hàng đợi.

val myWorkRequest = ...
WorkManager.getInstance(myContext).enqueue(myWorkRequest)

WorkRequest myWorkRequest = ...
WorkManager.getInstance(myContext).enqueue(myWorkRequest);

Đối tượng WorkRequest chứa tất cả thông tin mà WorkManager cần để lên lịch và chạy công việc. Đối tượng này bao gồm các quy tắc ràng buộc mà hệ thống phải đáp ứng để chạy công việc, thông tin lên lịch, chẳng hạn như khoảng thời gian trễ hoặc khoảng thời gian lặp lại, cấu hình thử lại và có thể chứa dữ liệu đầu vào nếu công việc của bạn phụ thuộc vào dữ liệu đó.

Bản thân WorkRequest là một lớp cơ sở trừu tượng. Có hai cách triển khai phát sinh của lớp này mà bạn có thể sử dụng để tạo yêu cầu, là OneTimeWorkRequest và PeriodicWorkRequest. Giống như ý nghĩa tên của chúng, OneTimeWorkRequest rất hữu ích để lên lịch cho công việc không lặp lại, trong khi PeriodicWorkRequest thích hợp hơn để lên lịch cho công việc lặp lại vào một khoảng thời gian nào đó.

Thao tác lên lịch cho công việc một lần

Đối với công việc đơn giản mà hệ thống không yêu cầu cấu hình bổ sung, hãy sử dụng phương thức tĩnh from:

val myWorkRequest = OneTimeWorkRequest.from(MyWork::class.java)

WorkRequest myWorkRequest = OneTimeWorkRequest.from(MyWork.class);

Để thực hiện công việc phức tạp hơn, bạn có thể dùng trình tạo:

val uploadWorkRequest: WorkRequest =
   OneTimeWorkRequestBuilder<MyWork>()
       // Additional configuration
       .build()

WorkRequest uploadWorkRequest =
   new OneTimeWorkRequest.Builder(MyWork.class)
       // Additional configuration
       .build();

Lên lịch cho công việc ưu tiên

WorkManager 2.7.0 đã giới thiệu khái niệm về công việc ưu tiên. Tính năng này giúp WorkManager thực thi các công việc quan trọng, đồng thời, cho phép hệ thống kiểm soát tốt hơn quyền truy cập vào các tài nguyên.

Tính năng công việc ưu tiên đáng chú ý vì những đặc điểm sau:

• Tầm quan trọng: Tính năng công việc ưu tiên phù hợp với các tác vụ quan trọng đối với người dùng hoặc do người dùng bắt đầu.
• Tốc độ: Công việc ưu tiên phù hợp nhất với các tác vụ ngắn bắt đầu ngay lập tức và hoàn thành trong vòng vài phút.
• Hạn mức: Hạn mức cấp hệ thống giới hạn thời gian thực thi trong nền trước sẽ xác định xem liệu có thể bắt đầu một công việc ưu tiên hay không.
• Quản lý điện năng: Các hạn chế về quản lý điện năng, chẳng hạn như Trình tiết kiệm pin và chế độ Nghỉ, có ít khả năng ảnh hưởng đến công việc ưu tiên hơn.
• Độ trễ: Hệ thống ngay lập tức thực thi công việc ưu tiên, miễn là khối lượng công việc hiện tại của hệ thống cho phép làm như vậy. Điều này có nghĩa là công việc ưu tiên nhạy cảm với độ trễ và không thể bị dời lịch để thực thi sau này.

Một trường hợp sử dụng tiềm năng của tính năng công việc ưu tiên có thể nằm trong ứng dụng nhắn tin khi người dùng muốn gửi tin nhắn hoặc một hình ảnh đính kèm. Tương tự như vậy, một ứng dụng xử lý quy trình thanh toán hoặc quy trình thuê bao cũng có thể cần đến tính năng công việc ưu tiên. Lý do là những tác vụ đó có ý nghĩa quan trọng với người dùng, thực thi nhanh trong nền, cần bắt đầu ngay lập tức và sẽ tiếp tục thực thi ngay cả khi người dùng đóng ứng dụng

Hạn mức

Trước khi hệ thống có thể chạy, nó phải phân bổ thời gian thực thi cho một công việc ưu tiên. Thời gian thực thi không phải là không giới hạn. Thay vào đó, mỗi ứng dụng sẽ nhận được một hạn mức thời gian thực thi. Khi ứng dụng dùng hết thời gian thực thi của nó và đạt đến hạn mức phân bổ, bạn sẽ không thể thực thi công việc ưu tiên nữa cho đến khi làm mới hạn mức. Điều này cho phép Android cân bằng tài nguyên giữa các ứng dụng một cách hiệu quả hơn.

Thời lượng thực thi có sẵn cho một ứng dụng dựa trên bộ chứa của chế độ chờ và tầm quan trọng của quy trình.

Bạn có thể xác định điều gì xảy ra khi hạn mức thực thi không cho phép chạy một công việc ưu tiên ngay lập tức. Hãy xem các đoạn mã dưới đây để biết thông tin chi tiết.

Thực thi công việc ưu tiên

Kể từ WorkManager 2.7, ứng dụng của bạn có thể gọi setExpedited() để khai báo rằng WorkRequest sẽ chạy nhanh nhất có thể bằng cách sử dụng tính năng công việc ưu tiên. Đoạn mã sau đây cung cấp ví dụ về cách sử dụng setExpedited():

val request = OneTimeWorkRequestBuilder<SyncWorker>()
    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
    .build()

WorkManager.getInstance(context)
    .enqueue(request)

OneTimeWorkRequest request = new OneTimeWorkRequestBuilder<T>()
    .setInputData(inputData)
    .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST)
    .build();

Trong ví dụ này, chúng tôi khởi động một thực thể của OneTimeWorkRequest và gọi setExpedited() trên thực thể đó. Yêu cầu này sau đó sẽ chuyển thành công việc ưu tiên. Nếu hạn mức cho phép, thì công việc ưu tiên đó sẽ bắt đầu chạy ngay lập tức trong nền. Nếu hạn mức đã được sử dụng, tham số OutOfQuotaPolicy sẽ cho biết rằng yêu cầu sẽ được chạy như công việc thông thường, không phải công việc ưu tiên.

Khả năng tương thích ngược và các dịch vụ trên nền trước

Để duy trì khả năng tương thích ngược cho các công việc ưu tiên, WorkManager có thể chạy một dịch vụ trên nền trước trên các phiên bản nền tảng cũ hơn Android 12. Các dịch vụ trên nền trước có thể hiển thị thông báo cho người dùng.

Các phương thức getForegroundInfoAsync() và getForegroundInfo() trong Worker cho phép WorkManager hiển thị thông báo khi bạn gọi setExpedited() trước Android 12.

Mọi ListenableWorker đều phải triển khai phương thức getForegroundInfo nếu bạn muốn yêu cầu tác vụ đó chạy dưới dạng một công việc ưu tiên.

Khi nhắm đến Android 12 trở lên, bạn sẽ luôn có khả năng sử dụng các dịch vụ trên nền trước thông qua phương thức setForeground tương ứng.

Worker

Worker không biết liệu công việc mà trình đang thực hiện có được ưu tiên hay không. Tuy nhiên, các worker có thể hiển thị thông báo trên một số phiên bản Android khi hệ thống đã ưu tiên một WorkRequest.

Để bật tính năng này, WorkManager sẽ cung cấp phương thức getForegroundInfoAsync(). Bạn phải triển khai phương thức này để WorkManager có thể hiển thị thông báo nhằm bắt đầu một ForegroundService khi cần thiết.

CoroutineWorker

Nếu bạn sử dụng một CoroutineWorker, thì bạn phải triển khai getForegroundInfo(). Sau đó, hãy truyền tham số đó đến setForeground() trong phạm vi doWork(). Làm như vậy sẽ tạo ra thông báo trong các phiên bản Android trước 12.

Hãy xem ví dụ sau đây:

  class ExpeditedWorker(appContext: Context, workerParams: WorkerParameters):
   CoroutineWorker(appContext, workerParams) {

   override suspend fun getForegroundInfo(): ForegroundInfo {
       return ForegroundInfo(
           NOTIFICATION_ID, createNotification()
       )
   }

   override suspend fun doWork(): Result {
       TODO()
   }

    private fun createNotification() : Notification {
       TODO()
    }

}

Các chính sách về hạn mức

Bạn có thể kiểm soát điều gì sẽ xảy ra với công việc ưu tiên khi ứng dụng của bạn đạt đến hạn mức thực thi. Để tiếp tục, bạn có thể truyền setExpedited():

• OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST. Tham số này sẽ khiến công việc chạy dưới dạng một yêu cầu công việc thông thường. Đoạn mã ở trên minh hoạ điều này.
• OutOfQuotaPolicy.DROP_WORK_REQUEST. Tham số này sẽ dẫn đến việc huỷ yêu cầu nếu không có đủ hạn mức.

Ứng dụng mẫu

Để xem ví dụ đầy đủ về cách WorkManager 2.7.0 sử dụng công việc ưu tiên, hãy xem qua phần WorkManagerSample trên GitHub.

Trì hoãn công việc ưu tiên

Hệ thống sẽ cố gắng thực thi một công việc ưu tiên đã thiết lập nhanh nhất có thể sau khi gọi công việc. Tuy nhiên, cũng như trong trường hợp với các loại công việc khác, hệ thống có thể trì hoãn quá trình bắt đầu của công việc ưu tiên mới, chẳng hạn như trong các trường hợp sau:

• Khả năng tải: Hệ thống quá tải, có thể xảy ra khi có quá nhiều công việc đang chạy hoặc khi hệ thống không có đủ bộ nhớ.
• Hạn mức: Hệ thống đã vượt quá giới hạn của hạn mức công việc ưu tiên. Công việc ưu tiên sử dụng một hệ thống hạn mức dựa trên Bộ chứa của chế độ chờ ứng dụng và công việc này giới hạn thời gian thực thi tối đa trong một khoảng thời gian luân phiên. Hạn mức dùng cho công việc ưu tiên có tính hạn chế cao hơn so với hạn mức dùng cho các loại công việc trong nền khác.

Lên lịch cho công việc định kỳ

Đôi khi, ứng dụng của bạn có thể yêu cầu phải định kỳ chạy một số công việc nhất định. Ví dụ: Bạn có thể muốn sao lưu dữ liệu định kỳ, tải nội dung mới trong ứng dụng xuống hoặc tải nhật ký lên máy chủ.

Dưới đây là cách bạn sử dụng PeriodicWorkRequest để tạo một đối tượng WorkRequest sẽ thực thi định kỳ:

val saveRequest =
       PeriodicWorkRequestBuilder<SaveImageToFileWorker>(1, TimeUnit.HOURS)
    // Additional configuration
           .build()

PeriodicWorkRequest saveRequest =
       new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class, 1, TimeUnit.HOURS)
           // Constraints
           .build();

Trong ví dụ này, công việc được lên lịch với khoảng thời gian một giờ.

Khoảng thời gian được định nghĩa là thời gian tối thiểu giữa các lần lặp lại. Thời gian chính xác mà worker sẽ được thực thi phụ thuộc vào các điều kiện ràng buộc mà bạn đang dùng trong đối tượng WorkRequest và trên các tính năng tối ưu hoá mà hệ thống thực hiện.

Khoảng thời gian chạy linh hoạt

Nếu bản chất của công việc khiến công việc đó nhạy cảm với thời gian chạy, thì bạn có thể định cấu hình PeriodicWorkRequest để chạy trong một khoảng thời gian linh hoạt bên trong từng khoảng thời gian, như trong Hình 1.

Hình 1. Sơ đồ này cho thấy các khoảng thời gian lặp lại có khoảng thời gian linh hoạt mà công việc có thể chạy.

Để xác định công việc định kỳ có khoảng thời gian linh hoạt, hãy truyền flexInterval cùng với repeatInterval khi tạo PeriodicWorkRequest. Khoảng thời gian linh hoạt bắt đầu từ repeatInterval - flexInterval và chạy đến cuối khoảng thời gian.

Sau đây là ví dụ về công việc định kỳ có thể chạy trong 15 phút cuối cùng của mỗi khoảng thời gian một giờ.

val myUploadWork = PeriodicWorkRequestBuilder<SaveImageToFileWorker>(
       1, TimeUnit.HOURS, // repeatInterval (the period cycle)
       15, TimeUnit.MINUTES) // flexInterval
    .build()

WorkRequest saveRequest =
       new PeriodicWorkRequest.Builder(SaveImageToFileWorker.class,
               1, TimeUnit.HOURS,
               15, TimeUnit.MINUTES)
           .build();

Khoảng thời gian lặp lại phải lớn hơn hoặc bằng PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS và khoảng thời gian linh hoạt phải lớn hơn hoặc bằng PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS.

Ảnh hưởng của các quy tắc ràng buộc đối với công việc định kỳ

Bạn có thể áp dụng các điều kiện ràng buộc đối với công việc định kỳ. Ví dụ: Bạn có thể thêm một điều kiện ràng buộc vào yêu cầu công việc để công việc đó chỉ chạy khi thiết bị của người dùng đang sạc. Trong trường hợp này, ngay cả khi khoảng thời gian lặp lại đã xác định trôi qua, PeriodicWorkRequest sẽ không chạy cho đến khi đáp ứng điều kiện này. Việc này có thể khiến một quá trình chạy công việc cụ thể bị trì hoãn hay thậm chí là bỏ qua nếu không đáp ứng các điều kiện trong khoảng thời gian chạy.

Các điều kiện ràng buộc đối với công việc

Các điều kiện ràng buộc đảm bảo rằng hệ thống trì hoãn công việc cho đến khi đáp ứng được các điều kiện tối ưu. Các điều kiện ràng buộc sau có sẵn cho WorkManager.

Để tạo một tập hợp các điều kiện ràng buộc và liên kết tập hợp đó với công việc nào đó, hãy tạo một thực thể Constraints bằng cách sử dụng Contraints.Builder() và gán thực thể đó cho WorkRequest.Builder().

Ví dụ: Mã sau đây xây dựng một yêu cầu công việc chỉ chạy khi thiết bị của người dùng vừa sạc vừa kết nối với Wi-Fi:

val constraints = Constraints.Builder()
   .setRequiredNetworkType(NetworkType.UNMETERED)
   .setRequiresCharging(true)
   .build()

val myWorkRequest: WorkRequest =
   OneTimeWorkRequestBuilder<MyWork>()
       .setConstraints(constraints)
       .build()

Constraints constraints = new Constraints.Builder()
       .setRequiredNetworkType(NetworkType.UNMETERED)
       .setRequiresCharging(true)
       .build();

WorkRequest myWorkRequest =
       new OneTimeWorkRequest.Builder(MyWork.class)
               .setConstraints(constraints)
               .build();

Khi bạn chỉ định nhiều điều kiện ràng buộc, công việc sẽ chỉ chạy khi đáp ứng tất cả điều kiện đó.

Trường hợp có một điều kiện ràng buộc chuyển sang trạng thái chưa được đáp ứng trong khi công việc của bạn đang chạy, thì WorkManager sẽ dừng worker của bạn. Công việc sẽ được thử lại sau khi hệ thống đã đáp ứng tất cả điều kiện ràng buộc.

Trì hoãn công việc

Trong trường hợp công việc của bạn không có điều kiện ràng buộc hoặc hệ thống đã đáp ứng tất cả điều kiện ràng buộc khi công việc được thêm vào hàng đợi, hệ thống có thể chọn chạy công việc đó ngay lập tức. Nếu bạn không muốn công việc đó chạy ngay lập tức, thì bạn có thể chỉ định cho công việc bắt đầu sau một khoảng thời gian trì hoãn tối thiểu ban đầu.

Dưới đây là ví dụ về cách thiết lập để công việc của bạn chạy sau khi công việc đó đã ở trong hàng đợi ít nhất 10 phút.

val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>()
   .setInitialDelay(10, TimeUnit.MINUTES)
   .build()

WorkRequest myWorkRequest =
      new OneTimeWorkRequest.Builder(MyWork.class)
               .setInitialDelay(10, TimeUnit.MINUTES)
               .build();

Mặc dù ví dụ minh hoạ cách thiết lập độ trễ ban đầu cho OneTimeWorkRequest, bạn cũng có thể thiết lập độ trễ ban đầu cho PeriodicWorkRequest. Trong trường hợp đó, hệ thống sẽ chỉ trì hoãn quá trình chạy đầu tiên của công việc định kỳ.

Thử lại và chính sách thời gian đợi

Nếu bạn yêu cầu WorkManager thử lại công việc của mình, thì bạn có thể trả về Result.retry() từ worker. Sau đó, công việc của bạn sẽ được lên lịch lại theo độ trễ thời gian đợi và chính sách thời gian đợi.

• Độ trễ thời gian đợi chỉ định thời gian chờ tối thiểu trước khi thử lại công việc sau lần thử đầu tiên. Giá trị này có thể không dưới 10 giây (hoặc MIN_BACKBACK_MILLIS).

• Chính sách thời gian đợi xác định độ trễ thời gian đợi sẽ tăng dần theo thời gian đối với các lần thử lại sau đó. WorkManager hỗ trợ 2 chính sách thời gian đợi, là LINEAR và EXPONENTIAL.

Mỗi yêu cầu công việc đều có chính sách thời gian đợi và độ trễ thời gian đợi. Chính sách mặc định là EXPONENTIAL với độ trễ là 30 giây, nhưng bạn có thể ghi đè chính sách này trong cấu hình yêu cầu công việc.

Sau đây là ví dụ về cách tuỳ chỉnh chính sách và độ trễ thời gian đợi.

val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>()
   .setBackoffCriteria(
       BackoffPolicy.LINEAR,
       OneTimeWorkRequest.MIN_BACKOFF_MILLIS,
       TimeUnit.MILLISECONDS)
   .build()

WorkRequest myWorkRequest =
       new OneTimeWorkRequest.Builder(MyWork.class)
               .setBackoffCriteria(
                       BackoffPolicy.LINEAR,
                       OneTimeWorkRequest.MIN_BACKOFF_MILLIS,
                       TimeUnit.MILLISECONDS)
               .build();

Trong ví dụ này, hệ thống thiết lập độ trễ thời gian đợi tối thiểu là giá trị tối thiểu cho phép, tương đương 10 giây. Vì chính sách này là LINEAR, nên khoảng thời gian thử lại sẽ tăng thêm khoảng 10 giây mỗi lần bạn thử lại. Ví dụ: Lần chạy đầu tiên kết thúc bằng Result.retry() sẽ được thử lại sau 10 giây, tiếp theo là 20, 30, 40, v.v. nếu công việc tiếp tục trả về Result.retry() sau những lần thử tiếp theo. Nếu bạn thiết lập chính sách thời gian đợi là EXPONENTIAL, thì trình tự thời gian thử lại sẽ gần hơn với 20, 40, 80, v.v.

Thao tác gắn thẻ công việc

Mỗi yêu cầu công việc có một giá trị nhận dạng duy nhất. Giá trị nhận dạng ấy sau này có thể dùng để xác định công việc đó nhằm huỷ công việc hoặc quan sát tiến trình công việc.

Nếu bạn có một nhóm công việc có liên quan về mặt logic, thì bạn cũng có thể thấy việc gắn thẻ các mục công việc đó rất hữu ích. Việc gắn thẻ cho phép bạn thao tác cùng với một nhóm các yêu cầu công việc.

Ví dụ: WorkManager.cancelAllWorkByTag(String) sẽ huỷ tất cả yêu cầu công việc có một thẻ cụ thể và WorkManager.getWorkInfosByTag(String) trả về một danh sách các đối tượng WorkInfo có thể dùng để xác định trạng thái công việc hiện tại.

Mã sau đây cho biết cách bạn có thể thêm thẻ "dọn dẹp" vào công việc của mình:

val myWorkRequest = OneTimeWorkRequestBuilder<MyWork>()
   .addTag("cleanup")
   .build()

WorkRequest myWorkRequest =
       new OneTimeWorkRequest.Builder(MyWork.class)
       .addTag("cleanup")
       .build();

Cuối cùng, bạn có thể thêm nhiều thẻ vào một yêu cầu công việc. Bên trong, các thẻ này được lưu trữ dưới dạng một tập hợp các chuỗi. Để tập hợp các thẻ liên kết với WorkRequest, bạn có thể sử dụng WorkInfo.getTag().

Từ lớp Worker, bạn có thể truy xuất tập hợp thẻ thông qua ListenableWorker.getTag().

Thao tác gán dữ liệu đầu vào

Để thực hiện công việc của bạn, hệ thống có thể yêu cầu dữ liệu đầu vào . Ví dụ: công việc xử lý việc tải hình ảnh lên có thể yêu cầu tải URI của hình ảnh lên dưới dạng đầu vào.

Hệ thống lưu trữ các giá trị đầu vào ở dạng các cặp khoá-giá trị trong đối tượng Data, đồng thời, hệ thống cũng có thể thiết lập các giá trị này trên yêu cầu công việc. WorkManager sẽ phân phối Data đầu vào cho công việc khi thực thi công việc đó. Lớp Worker có thể truy cập các đối số đầu vào bằng cách gọi Worker.getInputData(). Mã dưới đây cho biết cách bạn có thể tạo một thực thể Worker để yêu cầu dữ liệu đầu vào và cách gửi thực thể đó trong yêu cầu công việc.

// 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()

// 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();

Tương tự, bạn có thể sử dụng lớp Data để xuất một giá trị trả về. Dữ liệu đầu vào và đầu ra được trình bày chi tiết hơn trong mục tham số đầu vào và các giá trị trả về.

Các bước tiếp theo

Trên trang Trạng thái và quan sát, bạn sẽ tìm hiểu thêm về trạng thái công việc và cách theo dõi tiến trình công việc.