Arbeitsanfragen definieren

In der Anleitung „Erste Schritte“ wurde beschrieben, wie Sie eine WorkRequest und in die Warteschlange stellen.

In dieser Anleitung erfahren Sie, wie Sie WorkRequest-Objekte definieren und anpassen, um häufige Anwendungsfälle zu verarbeiten, z. B.:

• Einmalige und wiederkehrende Arbeit planen
• Arbeitseinschränkungen festlegen, z. B. WLAN oder Aufladen erforderlich
• Mindestverzögerung bei der Ausführung von Arbeit garantieren
• Strategien für Wiederholungen und Backoff festlegen
• Eingabedaten an die Arbeit übergeben
• Zusammengehörige Arbeit mit Tags gruppieren

Übersicht

Arbeit wird in WorkManager mit einer WorkRequest definiert. Wenn Sie Arbeit mit WorkManager planen möchten, müssen Sie zuerst ein WorkRequest-Objekt erstellen und es dann in die Warteschlange stellen.

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

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

Das WorkRequest-Objekt enthält alle Informationen, die WorkManager zum Planen und Ausführen Ihrer Arbeit benötigt. Dazu gehören Einschränkungen, die erfüllt sein müssen, damit Ihre Arbeit ausgeführt werden kann, Planungsinformationen wie Verzögerungen oder Wiederholungsintervalle, die Konfiguration für Wiederholungen und möglicherweise Eingabedaten, wenn Ihre Arbeit davon abhängt.

WorkRequest selbst ist eine abstrakte Basisklasse. Es gibt zwei abgeleitete Implementierungen dieser Klasse, mit denen Sie die Anfrage erstellen können: OneTimeWorkRequest und PeriodicWorkRequest. Wie die Namen schon sagen, ist OneTimeWorkRequest nützlich, um nicht wiederkehrende Arbeit zu planen, während PeriodicWorkRequest besser geeignet ist, um Arbeit zu planen, die in einem bestimmten Intervall wiederholt wird.

Einmalige Arbeit planen

Für einfache Arbeit, für die keine zusätzliche Konfiguration erforderlich ist, verwenden Sie die statische Methode from:

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

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

Für komplexere Arbeit können Sie einen Builder verwenden:

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

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

Express-Job planen

Mit WorkManager 2.7.0 wurde das Konzept der Express-Jobs eingeführt. So kann WorkManager wichtige Arbeit ausführen und gleichzeitig dem System eine bessere Kontrolle über den Zugriff auf Ressourcen geben.

Express-Jobs zeichnen sich durch die folgenden Merkmale aus:

• Wichtigkeit: Express-Jobs eignen sich für Aufgaben, die für den Nutzer wichtig sind oder vom Nutzer initiiert werden.
• Geschwindigkeit: Express-Jobs sind am besten für kurze Aufgaben geeignet, die sofort gestartet und innerhalb weniger Minuten abgeschlossen werden.
• Kontingente: Ein Kontingent auf Systemebene, das die Ausführungszeit im Vordergrund begrenzt, bestimmt, ob ein Express-Job gestartet werden kann.
• Energieverwaltung: Einschränkungen bei der Energieverwaltung wie Battery Saver und Doze wirken sich weniger auf Express-Jobs aus.
• Latenz: Das System führt Express-Jobs sofort aus, sofern die aktuelle Arbeitslast des Systems dies zulässt. Das bedeutet, dass sie latenz empfindlich sind und nicht für eine spätere Ausführung geplant werden können.

Ein möglicher Anwendungsfall für Express-Jobs ist eine Chat-App, wenn der Nutzer eine Nachricht oder ein angehängtes Bild senden möchte. Ebenso kann eine App, die einen Zahlungs- oder Abo-Ablauf verarbeitet, Express-Jobs verwenden. Das liegt daran, dass diese Aufgaben für den Nutzer wichtig sind, schnell im Hintergrund ausgeführt werden, sofort beginnen müssen und auch dann ausgeführt werden sollten, wenn der Nutzer die App schließt.

Kontingente

Das System muss einem Express-Job Ausführungszeit zuweisen, bevor er ausgeführt werden kann. Die Ausführungszeit ist nicht unbegrenzt. Stattdessen erhält jede App ein Kontingent an Ausführungszeit. Wenn Ihre App ihre Ausführungszeit nutzt und das zugewiesene Kontingent erreicht, können Sie keine Express-Jobs mehr ausführen, bis das Kontingent aktualisiert wird. So kann Android Ressourcen effektiver zwischen Anwendungen ausgleichen.

Die einer App zur Verfügung stehende Ausführungszeit basiert auf dem Standby-Bucket und der Prozesswichtigkeit.

Sie können festlegen, was passiert, wenn das Ausführungskontingent die sofortige Ausführung eines Express-Jobs nicht zulässt. Weitere Informationen finden Sie in den folgenden Snippets.

Express-Job ausführen

Ab WorkManager 2.7 kann Ihre App setExpedited() aufrufen, um zu deklarieren, dass eine WorkRequest so schnell wie möglich mit einem Express-Job ausgeführt werden soll. Das folgende Code-Snippet zeigt ein Beispiel für die Verwendung von setExpedited():

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

WorkManager.getInstance(context)
    .enqueue(request)

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

In diesem Beispiel initialisieren wir eine Instanz von OneTimeWorkRequest und rufen setExpedited() dafür auf. Diese Anfrage wird dann zu einem Express-Job. Wenn das Kontingent es zulässt, wird sie sofort im Hintergrund ausgeführt. Wenn das Kontingent aufgebraucht ist, gibt der Parameter OutOfQuotaPolicy an, dass die Anfrage als normaler, nicht beschleunigter Job ausgeführt werden soll.

Abwärtskompatibilität und Dienste im Vordergrund

Um die Abwärtskompatibilität für Express-Jobs beizubehalten, führt WorkManager möglicherweise einen Dienst im Vordergrund auf Plattformversionen aus, die älter als Android 12 sind. Dienste im Vordergrund können dem Nutzer eine Benachrichtigung anzeigen.

Mit den Methoden getForegroundInfoAsync() und getForegroundInfo() in Ihrem Worker kann WorkManager eine Benachrichtigung anzeigen, wenn Sie setExpedited() vor Android 12 aufrufen.

Jeder ListenableWorker muss die Methode getForegroundInfo implementieren, wenn Sie anfordern möchten, dass die Aufgabe als Express-Job ausgeführt wird.

Wenn Sie Android 12 oder höher verwenden, stehen Ihnen Dienste im Vordergrund weiterhin über die entsprechende Methode setForeground zur Verfügung.

Worker

Worker wissen nicht, ob die Arbeit, die sie ausführen, beschleunigt wird oder nicht. Auf einigen Android-Versionen können Worker jedoch eine Benachrichtigung anzeigen, wenn eine WorkRequest beschleunigt wurde.

Dazu stellt WorkManager die Methode getForegroundInfoAsync() bereit, die Sie implementieren müssen, damit WorkManager bei Bedarf eine Benachrichtigung anzeigen kann, um einen ForegroundService für Sie zu starten.

CoroutineWorker

Wenn Sie einen CoroutineWorker verwenden, müssen Sie getForegroundInfo() implementieren. Anschließend übergeben Sie ihn in doWork() an setForeground(). Dadurch wird die Benachrichtigung in Android-Versionen vor 12 erstellt.

Dazu ein Beispiel:

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

}

Kontingentrichtlinien

Sie können festlegen, was mit Express-Jobs passiert, wenn Ihre App ihr Ausführungskontingent erreicht. Dazu können Sie setExpedited() übergeben:

• OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST, wodurch der Job als normale Arbeitsanfrage ausgeführt wird. Das vorherige Snippet zeigt dies.
• OutOfQuotaPolicy.DROP_WORK_REQUEST, wodurch die Anfrage abgebrochen wird, wenn nicht genügend Kontingent vorhanden ist.

Verzögerte Express-Jobs

Das System versucht, einen bestimmten Express-Job so schnell wie möglich nach dem Aufruf auszuführen. Wie bei anderen Jobtypen kann das System den Start neuer Express-Jobs jedoch verzögern, z. B. in den folgenden Fällen:

• Auslastung: Die Systemauslastung ist zu hoch. Das kann passieren, wenn bereits zu viele Jobs ausgeführt werden oder wenn das System nicht genügend Arbeitsspeicher hat.
• Kontingent: Das Kontingentlimit für Express-Jobs wurde überschritten. Für Express-Jobs wird ein Kontingentsystem verwendet, das auf den App-Standby-Buckets basiert und die maximale Ausführungszeit innerhalb eines rollierenden Zeitfensters begrenzt. Die für Express-Jobs verwendeten Kontingente sind restriktiver als die für andere Arten von Hintergrundjobs.

Wiederkehrende Arbeit planen

Manchmal muss Ihre App bestimmte Arbeit regelmäßig ausführen. Sie können beispielsweise regelmäßig Ihre Daten sichern, neue Inhalte in Ihre App herunterladen oder Logs auf einen Server hochladen.

So erstellen Sie mit PeriodicWorkRequest ein WorkRequest Objekt, das regelmäßig ausgeführt wird:

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

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

In diesem Beispiel wird die Arbeit in einem Intervall von einer Stunde geplant.

Das Intervall wird als Mindestzeit zwischen Wiederholungen definiert. Der genaue Zeitpunkt, zu dem der Worker ausgeführt wird, hängt von den Einschränkungen ab, die Sie in Ihrem WorkRequest-Objekt verwenden, und von den Optimierungen, die vom System vorgenommen werden.

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

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

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

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

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

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

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

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

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