İş isteklerini tanımlama

Başlangıç kılavuzunda, basit bir WorkRequest oluşturma işleminin nasıl yapılacağı ele alınmıştı. ve sıraya sokacağım.

Bu kılavuzda WorkRequest nesnelerini tanımlamayı ve özelleştirmeyi öğreneceksiniz. Örneğin:

• Tek seferlik ve yinelenen işler programlama
• Kablosuz ağ veya şarj etme gibi iş kısıtlamaları ayarlayın
• İşin yürütülmesinde minimum gecikme yaşanmasını garanti etmek
• Yeniden deneme ve geri alma stratejileri belirleyin
• Giriş verilerini işe aktarın
• Etiketleri kullanarak ilgili işleri gruplandırın

Genel Bakış

İş Yöneticisi, WorkRequest aracılığıyla tanımlanır. Bu amaçla WorkManager ile çalışmanızı planlamak için öncelikle WorkRequest nesneyi sıraya ekleyin.

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

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

WorkRequest nesnesi, WorkManager'ın şunları yapması için gereken tüm bilgileri ve yönetmenin en iyi yoludur. Bu, dönüşümünüz için karşılanması gereken kısıtlamalar çalışmayı sürdürme, gecikmeler veya yinelenen aralıklar gibi bilgileri planlama, tekrar deneme ve çalışmanız gerekiyorsa giriş verilerini de içerebilir.

WorkRequest soyut bir temel sınıftır. İki tür isteği oluşturmak için kullanabileceğiniz, bu sınıfın türetilmiş uygulamalarını OneTimeWorkRequest ve PeriodicWorkRequest. Adlarından da anlaşılacağı gibi OneTimeWorkRequest, planlama için kullanışlıdır tekrarlanmayan işler için PeriodicWorkRequest daha uygundur. ve belli aralıklarla tekrarlanan işler zaman çizelgesi oluşturur.

Tek seferlik çalışma programlama

Ek yapılandırma gerektirmeyen basit işler için yöntem from:

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

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

Daha karmaşık işler için bir oluşturucu kullanabilirsiniz:

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

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

Hızlandırılmış işler için zaman belirleyin

WorkManager 2.7.0 hızlandırılmış çalışma kavramını ortaya attı. Bu da WorkManager'ın sisteme daha iyi kontrol sağlarken önemli işleri yürütmesine de olanak tanır fazla erişimleri olabilir.

Hızlandırılmış çalışmalarda şu özellikler öne çıkar:

• Önem: Hızlandırılmış çalışmalar, kullanıcı veya ekip için önemli olan kullanıcılar tarafından başlatılır.
• Hız: Hızlandırılmış çalışmalar en çok, hemen başlayan ve kısa süren görevler için uygundur birkaç dakika içinde tamamlanır.
• Kotalar: Ön plan yürütme süresini sınırlayan sistem düzeyinde bir kota bir işin başlayıp başlamayacağını belirler.
• Güç Yönetimi: Pil gibi güç yönetimi kısıtlamaları Tasarruf ve Doz özelliklerinin hızlandırılmış işi etkileme olasılığı daha düşüktür.
• Gecikme: Sistem, aşağıdaki durumlarda hızlandırılmış işi hemen yürütür. mevcut iş yükü bunu mümkün kılıyor. Bu nedenle, gecikme ve daha sonra yürütülmesi için planlanamaz.

Hızlandırılmış iş için olası bir kullanım alanı, kullanıcı ilk kez bir sohbet uygulaması mesaj veya ekli bir resim göndermek istiyor. Benzer şekilde, bir ya da abonelik akışında hızlandırılmış işleri de kullanmak gerekebilir. Bu çünkü bu görevler kullanıcı için önemlidir çünkü hemen başlaması ve hatta süreçlerde bile devam etmesi gerekir. Kullanıcı uygulamayı kapatırsa

Kotalar

Sistem, yürütme süresini işin tamamlanmasından önce hızlandırılmış bir işe ayırmalıdır çalıştırılabilir. Yürütme süresi sınırsız değildir. Bunun yerine her uygulama bir kota alır iki kat daha fazla olabilir. Uygulamanız yürütme süresini kullanıp sonuna ulaştığında bir kota varsa, ilgili kota dolana kadar hızlandırılmış işleri yenilenir. Bu da Android'in kaynakları arasındaki dengeyi kurmasına olanak tanır. izin verir.

Bir uygulamanın çalıştırılabileceği süre, beklemedeki paket ve sürecin önemi.

Yürütme kotası, bir işin hemen yürütülmesine neden olabilir. Ayrıntılı bilgi için aşağıdaki snippet'lere bakın.

Hızlandırılmış işleri yürütme

WorkManager 2.7'den itibaren uygulamanız setExpedited() öğesini çağırarak şunu beyan edebilir: WorkRequest, hızlandırılmış bir iş kullanarak mümkün olduğunca hızlı çalışmalıdır. İlgili içeriği oluşturmak için kullanılan Aşağıdaki kod snippet'i, setExpedited() özelliğinin nasıl kullanılacağına dair bir örnek sunar:

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

Bu örnekte, bir OneTimeWorkRequest örneğini başlatıyoruz ve Tamam, setExpedited() tane. Bu istek hızlandırılmış iş haline gelir. Kota arka planda hemen çalışmaya başlar. Kota kullanılıyorsa OutOfQuotaPolicy parametresi, isteğin hızlandırılmış olmayan bir şekilde yürütülmelidir.

Geriye dönük uyumluluk ve ön plan hizmetleri

Hızlandırılmış işlerin geriye dönük uyumluluğu sağlamak amacıyla WorkManager, Android 12'den eski platform sürümlerinde bir ön plan hizmeti çalıştırabilir. Ön plan hizmetleri kullanıcıya bildirim gösterebilir.

Çalışanınızdaki getForegroundInfoAsync() ve getForegroundInfo() yöntemleri setExpedited() çağrısı yaptığınızda WorkManager'ın bir bildirim görüntülemesini etkinleştir önceki sürümlerdir.

Aşağıdaki şartları karşılıyorsanız tüm ListenableWorker, getForegroundInfo yöntemini uygulamalıdır: görevin hızlandırılmış bir iş olarak çalışmasını talep ediyor.

Android 12 veya sonraki sürümleri hedeflediğinizde, ön plan hizmetleri ilgili setForeground yoluyla size geri dönebilir.

Çalışan

Çalışanlar, yaptıkları işin hızlandırılıp hızlandırılmadığını bilmiyor. Ama kullanıcılar, Android'in bazı sürümlerinde bir bildirim görüntüleyebilir. WorkRequest işleminin hızı hızlandırıldı.

WorkManager, bunu sağlamak için getForegroundInfoAsync() yöntemini sağlar. WorkManager'ın bir bildirim görüntüleyebilmesi için uygulamanız gereken ForegroundService.

Eş yordam çalışanı

CoroutineWorker kullanıyorsanız getForegroundInfo() uygulamanız gerekir. Siz de doWork() içinde setForeground() adlı kullanıcıya iletilecek. Bu, Android 12'den önceki sürümlerinde bu bildirime yönelik bildirim alırsınız.

Aşağıdaki örneği inceleyin:

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

}

Kota politikaları

Uygulamanız belirtilen hedefe ulaştığında hızlandırılmış çalışmaya ne olacağını kontrol edebilirsiniz. yürütme kotasıdır. Devam etmek için setExpedited() ayarını geçirebilirsiniz:

• OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST, bu da işin işlem isteği olarak çalışır. Yukarıdaki snippet bunu göstermektedir.
• OutOfQuotaPolicy.DROP_WORK_REQUEST, bu da isteğin iptal edilmesine neden olur. yeterli kota yok.

Örnek uygulama

WorkManager 2.7.0'ın hızlandırılmış işi nasıl kullandığına dair tam bir örnek için GitHub'daki WorkManagerSample üzerinden de geçebilirsiniz.

Ertelenen, hızlandırılmış çalışma

Sistem, hızlandırılmış bir işi, o andan itibaren mümkün olan en kısa sürede işi çağrılır. Ancak diğer iş türlerinde olduğu gibi, aşağıdaki durumlarda olduğu gibi hızlandırılmış yeni çalışmaların başlamasını geciktirebilir:

• Yük: Sistem yükü çok fazla. Bu durum, çok fazla işin olduğunu ya da sistemde yeterli bellek kalmadığını gösterir.
• Kota: Hızlandırılmış iş kotası sınırı aşıldı. Hızlandırılmış çalışma Uygulama Bekleme Paketlerine dayalı bir kota sistemi kullanır ve maksimum yürütme süresi belirleyin. Şunun için kullanılan kotalar: hızlandırılmış işler, diğer türlerdeki görevlere göre daha kısıtlayıcıdır. nasıl kullanabileceğinizi göstereceğiz.

Periyodik işler planlayın

Uygulamanız zaman zaman belirli işlerin düzenli olarak çalıştırılmasını gerektirebilir. Örneğin, verilerinizi düzenli aralıklarla yedeklemek, veya günlükleri bir sunucuya yükleyebilirsiniz.

Aşağıda, PeriodicWorkRequest öğesi oluşturmak için Düzenli olarak çalışan WorkRequest nesnesi:

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

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

Bu örnekte, çalışma bir saatlik aralıklarla planlanmıştır.

Aralık süresi, tekrarlar arasındaki minimum süre olarak tanımlanır. İlgili içeriği oluşturmak için kullanılan çalışanın yürütüleceği tam zaman kısıtlamalara bağlıdır yaptığınız optimizasyonlara ilişkin sistem tarafından belirlenir.

Esnek çalıştırma aralıkları

Çalışmanızın yapısı nedeniyle çalışma zamanlaması hassasiyeti taşıyorsa PeriodicWorkRequest, bir esnek çizgide koşmak için süre'yi tıklayın.

Şekil 1. Diyagram, işleyeceğiz.

Esnek dönemle düzenli çalışmayı tanımlamak için, esnek dönemle birlikte bir flexInterval geçirirsiniz. PeriodicWorkRequest oluştururken repeatInterval kullanın. Esnek dönem repeatInterval - flexInterval itibarıyla başlar ve aralığın sonuna kadar gider.

Aşağıda son 15 gün boyunca yürütülebilecek periyodik çalışmalara bir örnek verilmiştir. dakikası olabilir.

val myUploadWork = PeriodicWorkRequestBuilderS<aveImageToFileWorker(>
       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();

Tekrar aralığı en az olmalıdır PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS ve esnek aralık en az olmalıdır PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS.

Kısıtlamaların Periyodik Çalışma Üzerindeki Etki

Periyodik çalışmaya kısıtlamalar uygulayabilirsiniz. Örneğin, rapora bir için bir sınırlama getirmemelidir. Bu şekilde çalışma, yalnızca kullanıcı cihaz şarj oluyor. Bu durumda, tanımlanan tekrarlama aralığı geçse bile PeriodicWorkRequest bu koşul karşılanıncaya kadar çalışmaz. Bu çalışmasının belirli bir süre gecikmesine veya hatta koşullar çalıştırma aralığı içinde karşılanmazsa.

İş kısıtlamaları

Kısıtlamalar, çalışmanın en uygun koşullar karşılanana kadar ertelenmesini sağlar. Aşağıdaki kısıtlamalar WorkManager tarafından kullanılabilir.

Bir kısıtlama kümesi oluşturmak ve bunu bir çalışmayla ilişkilendirmek için Constraints örneğini Contraints.Builder() kullanarak oluşturup kendi WorkRequest.Builder().

Örneğin, aşağıdaki kod yalnızca Kullanıcının cihazı hem şarj oluyor hem de kablosuz ağa bağlı:

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

val myWorkRequest: WorkRequest =
   OneTimeWorkRequestBuilderM<yWork(>)
       .setConstraints(constraints)
       .build()

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

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

Birden çok sınırlama belirtildiğinde, çalışmanız yalnızca tüm da karşılanması gerekir.

Çalışmanız devam ederken bir kısıtlamanın karşılanmaması durumunda WorkManager, çalışanınızı durdurur. Çalışma, tüm yapılandırmaların da karşılanması gerekir.

Gecikmeli Çalışma

Çalışmanızda hiç kısıtlama olmaması veya tüm kısıtlamaların işiniz sıraya alındığında sistem, çalışmayı çalıştırmayı hemen teslim edebilirsiniz. Çalışmanın hemen çalıştırılmasını istemiyorsanız, gecikmeden sonra başlamasına olanak tanıyorum.

Çalışmanızı en az 10 dakika sonra çalışacak şekilde nasıl ayarlayacağınıza dair bir örnek sıraya alındı.

val myWorkRequest = OneTimeWorkRequestBuilderM<yWork(>)
   .setInitialDelay(10, TimeUnit.MINUTES)
   .build()

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

Bu örnekte, bir etkinlik için ilk gecikmenin nasıl OneTimeWorkRequest, isterseniz bir PeriodicWorkRequest. Bu durumda periyodik çalışmalarınızın yalnızca ilk kez çalıştırılması gecikecektir.

Yeniden deneme ve geri alma politikası

WorkManager'ın işinizi yeniden denemesini isterseniz Çalışanınızdan Result.retry(). Çalışmanız geri yükleme gecikmesi ve geri alma politikasına göre yeniden planlanmalıdır.

• Geri yükleme gecikmesi, yeniden denemeden önce beklenecek minimum süreyi belirtir emin olmanız gerekir. Bu değer 10 saniyeden kısa olamaz (veya MIN_BACKOFF_MILLIS).

• Geri yükleme politikası, geri yükleme gecikmesinin zaman içinde denemelerini devre dışı bırakabilirsiniz. WorkManager, 2 geri yükleme politikasını destekler. LINEAR ve EXPONENTIAL.

Her iş isteğinin bir geri alma politikası ve geri alma gecikmesi vardır. Varsayılan politika 30 saniyelik gecikmeyle EXPONENTIAL, ancak bunu şurada geçersiz kılabilirsiniz: iş isteği yapılandırması.

Aşağıda, geri yükleme gecikmesini ve politikasını özelleştirmeyle ilgili bir örnek verilmiştir.

val myWorkRequest = OneTimeWorkRequestBuilderM<yWork(>)
   .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();

Bu örnekte, minimum geri yükleme gecikmesi izin verilen minimum değere ayarlanmıştır. 10 saniye. Politika LINEAR olduğundan yeniden deneme aralığı yaklaşık 10 saniye sürer. Örneğin ilk çalıştırmada Result.retry() ile bitirme işlemi 10 saniye sonra tekrar denenecek, ardından 20, 30, 40 vs. Sonraki denemelerden sonra Result.retry(). Geri alma politikası EXPONENTIAL, yeniden deneme süresi dizisi 20, 40, 80 vb.’ye yakın olur. beklemeye gerek yoktur.

Etiket işi

Her iş isteğinin, aşağıdakileri tanımlamak için kullanılabilecek bir benzersiz tanımlayıcısı vardır kontrol ederek çalışmayı iptal etmek veya ilerleme durumunu gözlemlemek için kullanabilirsiniz.

Mantıksal olarak bağlantılı çalışmalardan oluşan bir grubunuz varsa, projeniz için etiketleyebilirsiniz. Etiketleme, bir grup işle çalışmanıza olanak tanır isteyebilirsiniz.

Örneğin, WorkManager.cancelAllWorkByTag(String) iptal eder belirli bir etikete sahip tüm iş istekleri ve WorkManager.getWorkInfosByTag(String), Mevcut çalışma durumunu belirlemek için kullanılabilecek WorkInfo nesneleri.

Aşağıdaki kod, bir "temizlik" işlemini nasıl ekleyebileceğinizi gösterir etiketi iş olarak ekleyin:

val myWorkRequest = OneTimeWorkRequestBuilderM<yWork(>)
   .addTag("cleanup")
   .build()

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

Son olarak, tek bir iş isteğine birden fazla etiket eklenebilir. Dahili olarak bu etiketleri, bir dize kümesi olarak depolanır. Şununla ilişkili etiket grubunu almak için: WorkInfo.getTags() işlevini kullanabileceğiniz WorkRequest öğesi.

Worker sınıfınızdan, etiket grubunu şu yolla alabilirsiniz: ListenableWorker.getTags() şeklinde ifade edilir.

Giriş verilerini atayın

Çalışmanız için giriş verileri gerekebilir. Örneğin, URL'sinin yüklenmesi, görselin URI'sının giriş.

Giriş değerleri, Data nesnesinde anahtar/değer çiftleri olarak depolanır ve iş isteğinde ayarlanabilir. WorkManager, Data girişini netleştirmeye yardımcı olur. Worker sınıfı erişebilir giriş bağımsız değişkenlerini Worker.getInputData() çağırarak oluşturun. İlgili içeriği oluşturmak için kullanılan aşağıdaki kod, her bir Worker örneğini nasıl oluşturabileceğinizi giriş verileri ve iş isteğinizde bu verilerin nasıl gönderileceğini gerektirir.

// 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 = OneTimeWorkRequestBuilderU<ploadWork(>)
   .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();

Benzer şekilde, Data sınıfı bir dönüş değeri oluşturmak için kullanılabilir. Giriş ve çıkış verileri; giriş parametreleri ve değerleri döndürür.

Sonraki Adımlar

Durumlar ve gözlem sayfasında, çalışma durumları hakkında daha fazla bilgi edinebilirsiniz. ilerlemesini nasıl izleyeceğinizi öğreneceksiniz.