Arbeitsanfragen definieren

Im Einstiegsleitfaden haben wir beschrieben, wie du eine einfache WorkRequest erstellst und in die Warteschlange einfügst.

In diesem Leitfaden erfahren Sie, wie Sie WorkRequest-Objekte für gängige Anwendungsfälle definieren und anpassen. Dazu gehören:

• Einmalige und wiederkehrende Aufgaben planen
• Arbeitseinschränkungen festlegen, z. B. WLAN oder Aufladen erforderlich
• Eine minimale Verzögerung bei der Ausführung von Aufgaben gewährleisten
• Strategien für Wiederholungen und Backoffs festlegen
• Eingabedaten an Workflow übergeben
• Ähnliche Aufgaben mithilfe von Tags gruppieren

Übersicht

Arbeit wird in WorkManager über eine WorkRequest definiert. Wenn Sie eine Aufgabe mit WorkManager planen möchten, müssen Sie zuerst ein WorkRequest-Objekt erstellen und dann in die Warteschlange einfügen.

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. Es enthält Einschränkungen, die erfüllt werden müssen, damit Ihre Arbeit ausgeführt werden kann, Planungsinformationen wie Verzögerungen oder wiederkehrende Intervalle, die Konfiguration für Wiederholungen und möglicherweise Eingabedaten, wenn diese für Ihre Arbeit erforderlich sind.

WorkRequest ist selbst eine abstrakte Basisklasse. Es gibt zwei abgeleitete Implementierungen dieser Klasse, mit denen Sie die Anfrage erstellen können: OneTimeWorkRequest und PeriodicWorkRequest. Wie die Namen andeuten, ist OneTimeWorkRequest nützlich für die Planung nicht wiederkehrender Aufgaben, während PeriodicWorkRequest besser für die Planung von Aufgaben geeignet ist, die in einem bestimmten Intervall wiederholt werden.

Einmalige Arbeit planen

Für einfache Aufgaben, die keine zusätzliche Konfiguration erfordern, verwenden Sie die statische Methode from:

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

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

Für komplexere Aufgaben 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

In WorkManager 2.7.0 wurde das Konzept des Express-Jobs eingeführt. So kann WorkManager wichtige Aufgaben ausführen und das System hat eine bessere Kontrolle über den Zugriff auf Ressourcen.

Express-Jobs zeichnen sich durch die folgenden Merkmale aus:

• Wichtigkeit: Die beschleunigte Bearbeitung eignet sich für Aufgaben, die für den Nutzer wichtig sind oder vom Nutzer initiiert werden.
• Geschwindigkeit: Beschleunigte Arbeit eignet sich am besten für kurze Aufgaben, die sofort beginnen und innerhalb weniger Minuten abgeschlossen werden.
• Kontingente: Ein Kontingent auf Systemebene, das die Ausführungszeit im Vordergrund begrenzt, bestimmt, ob ein beschleunigter Job gestartet werden kann.
• Energieverwaltung: Einschränkungen der Energieverwaltung wie der Energiesparmodus und der Ruhemodus wirken sich mit geringerer Wahrscheinlichkeit auf beschleunigte Aufgaben aus.
• Latenz: Das System führt die beschleunigte Arbeit sofort aus, sofern die aktuelle Arbeitslast des Systems dies zulässt. Das bedeutet, dass sie latenzempfindlich sind und nicht für eine spätere Ausführung geplant werden können.

Ein potenzieller Anwendungsfall für beschleunigte Arbeit könnte in einer Chat-App auftreten, wenn der Nutzer eine Nachricht oder ein angehängtes Bild senden möchte. Ähnlich kann bei einer App, die einen Zahlungs- oder Abovorgang verarbeitet, die beschleunigte Ausführung verwendet werden. Das liegt daran, dass diese Aufgaben für den Nutzer wichtig sind, schnell im Hintergrund ausgeführt werden, sofort beginnen und auch dann fortgesetzt werden sollten, wenn der Nutzer die App schließt.

Kontingente

Das System muss einem beschleunigten 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 die Ausführungszeit aufgebraucht hat und das zugewiesene Kontingent erreicht, können Sie erst wieder beschleunigte Aufgaben ausführen, wenn das Kontingent aktualisiert wurde. So kann Android die Ressourcen effektiver zwischen den Anwendungen verteilen.

Die für eine App verfügbare Ausführungszeit hängt vom Standby-Bucket und der Prozessbedeutung ab.

Sie können festlegen, was passiert, wenn aufgrund des Ausführungsquotats ein beschleunigter Job nicht sofort ausgeführt werden kann. Weitere Informationen finden Sie in den Snippets unten.

Express-Aufträge ausführen

Ab WorkManager 2.7 kann Ihre App setExpedited() aufrufen, um anzugeben, dass eine WorkRequest mit einem beschleunigten Job so schnell wie möglich ausgeführt werden soll. Das folgende Code-Snippet zeigt ein Beispiel für die Verwendung von 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();

In diesem Beispiel initialisieren wir eine Instanz von OneTimeWorkRequest und rufen setExpedited() darauf aus. Diese Anfrage wird dann vorrangig bearbeitet. Sofern das Kontingent dies zulässt, wird der Prozess sofort im Hintergrund ausgeführt. Wenn das Kontingent aufgebraucht ist, gibt der Parameter OutOfQuotaPolicy an, dass die Anfrage wie eine normale, nicht beschleunigte Anfrage ausgeführt werden soll.

Abwärtskompatibilität und Dienste im Vordergrund

Zur Aufrechterhaltung der Abwärtskompatibilität für beschleunigte Jobs führt WorkManager unter Plattformversionen älter als Android 12 möglicherweise einen Dienst im Vordergrund aus. Dienste im Vordergrund können dem Nutzer eine Benachrichtigung anzeigen.

Mit den Methoden getForegroundInfoAsync() und getForegroundInfo() in Ihrem Worker können Sie WorkManager dazu veranlassen, vor Android 12 eine Benachrichtigung anzuzeigen, wenn Sie setExpedited() aufrufen.

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

Wenn Ihre App auf Android 12 oder höher ausgerichtet ist, stehen Ihnen Dienste im Vordergrund weiterhin über die entsprechende setForeground-Methode zur Verfügung.

Worker

Die Mitarbeiter wissen nicht, ob die von ihnen ausgeführte Arbeit beschleunigt wird oder nicht. Bei einigen Android-Versionen können Kundenservicemitarbeiter 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 zum Starten eines ForegroundService anzeigt.

CoroutineWorker

Wenn Sie eine CoroutineWorker verwenden, müssen Sie getForegroundInfo() implementieren. Sie übergeben sie dann an setForeground() in doWork(). Dadurch wird die Benachrichtigung in Android-Versionen vor 12 erstellt.

Betrachten Sie das folgende 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 beschleunigten Aufgaben passiert, wenn Ihre App das Ausführungslimit erreicht. Sie haben folgende Möglichkeiten, um setExpedited() weiterzuleiten:

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

Beispiel-App

Ein vollständiges Beispiel dafür, wie WorkManager 2.7.0 beschleunigte Aufgaben verwendet, finden Sie im WorkManagerSample auf GitHub.

Verschobene Express-Aufträge

Das System versucht, einen bestimmten beschleunigten Job so schnell wie möglich nach dem Aufruf auszuführen. Wie bei anderen Arten von Jobs kann das System den Beginn neuer beschleunigter Arbeiten jedoch verschieben, 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 dem System nicht genügend Arbeitsspeicher zur Verfügung steht.
• Kontingent: Das Kontingent für beschleunigte Jobs wurde überschritten. Für die beschleunigte Verarbeitung wird ein Kontingentsystem verwendet, das auf den App-Standby-Buckets basiert und die maximale Ausführungszeit innerhalb eines rollierenden Zeitfensters begrenzt. Die Kontingente für beschleunigte Arbeiten sind strenger als die für andere Arten von Hintergrundjobs.

Regelmäßige Aufgaben planen

Für Ihre App müssen bestimmte Aufgaben möglicherweise regelmäßig ausgeführt werden. So können Sie beispielsweise regelmäßig Ihre Daten sichern, aktuelle Inhalte in Ihre App herunterladen oder Protokolle 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 ist die Arbeit mit einem Intervall von einer Stunde geplant.

Das Intervall ist die Mindestzeit zwischen den Wiederholungen. 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 durchgeführt werden.

Flexible Laufintervalle

Wenn die Art Ihrer Arbeit ein genaues Ausführen erfordert, können Sie PeriodicWorkRequest so konfigurieren, dass es innerhalb eines Flex-Zeitraums in jedem Intervall ausgeführt wird, wie in Abbildung 1 dargestellt.

Abbildung 1. Das Diagramm zeigt wiederkehrende Intervalle mit dem flexiblen Zeitraum, in dem die Arbeit ausgeführt werden kann.

Wenn Sie eine wiederkehrende Arbeit mit einem flexiblen Zeitraum definieren möchten, geben Sie beim Erstellen der PeriodicWorkRequest eine flexInterval zusammen mit der repeatInterval an. Der Flex-Zeitraum beginnt bei repeatInterval - flexInterval und endet am Ende des Intervalls.

Im folgenden Beispiel wird eine wiederkehrende Aufgabe beschrieben, die in den letzten 15 Minuten jeder Stunde ausgeführt werden kann.

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

Das Wiederholungsintervall muss größer oder gleich PeriodicWorkRequest.MIN_PERIODIC_INTERVAL_MILLIS und das flexible Intervall muss größer oder gleich PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS sein.

Auswirkungen von Einschränkungen auf wiederkehrende Aufgaben

Sie können Einschränkungen auf wiederkehrende Aufgaben anwenden. Sie können Ihrer Arbeitsanfrage beispielsweise eine Einschränkung hinzufügen, damit die Arbeit nur ausgeführt wird, wenn sich das Gerät des Nutzers gerade auflädt. In diesem Fall wird PeriodicWorkRequest erst ausgeführt, wenn diese Bedingung erfüllt ist, auch wenn das festgelegte Wiederholungsintervall verstrichen ist. Dies kann dazu führen, dass eine bestimmte Ausführung Ihrer Arbeit verzögert oder sogar übersprungen wird, wenn die Bedingungen nicht innerhalb des Ausführungsintervalls erfüllt werden.

Arbeitseinschränkungen

Mit Einschränkungen wird dafür gesorgt, dass die Arbeit verschoben wird, bis optimale Bedingungen vorliegen. Für WorkManager gelten die folgenden Einschränkungen.

Wenn Sie eine Reihe von Einschränkungen erstellen und mit einer Arbeit verknüpfen möchten, erstellen Sie eine Constraints-Instanz mithilfe der Contraints.Builder() und weisen Sie sie Ihrer WorkRequest.Builder() zu.

Mit dem folgenden Code wird beispielsweise eine Arbeitsanfrage erstellt, die nur ausgeführt wird, wenn sich das Gerät des Nutzers sowohl in der Ladestation befindet als auch mit dem WLAN verbunden ist:

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

Wenn mehrere Einschränkungen angegeben werden, wird Ihre Arbeit nur ausgeführt, wenn alle Einschränkungen erfüllt sind.

Wenn eine Einschränkung während der Ausführung der Arbeit nicht erfüllt wird, beendet WorkManager den Worker. Die Arbeit wird dann wiederholt, wenn alle Einschränkungen erfüllt sind.

Verzögerte Arbeit

Wenn Ihre Arbeit keine Einschränkungen hat oder alle Einschränkungen erfüllt sind, wenn Ihre Arbeit in die Warteschlange gestellt wird, führt das System die Arbeit möglicherweise sofort aus. Wenn die Arbeit nicht sofort ausgeführt werden soll, können Sie angeben, dass sie nach einer Mindestverzögerung gestartet werden soll.

Hier ist ein Beispiel dafür, wie Sie festlegen, dass Ihre Arbeit mindestens 10 Minuten nach der Aufnahme in die Warteschlange ausgeführt wird.

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

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

Im Beispiel wird gezeigt, wie eine anfängliche Verzögerung für eine OneTimeWorkRequest festgelegt wird. Sie können aber auch eine anfängliche Verzögerung für eine PeriodicWorkRequest festlegen. In diesem Fall wird nur die erste Ausführung der regelmäßigen Aufgabe verzögert.

Richtlinie für Wiederholungsversuche und Backoff

Wenn Sie möchten, dass WorkManager Ihre Arbeit noch einmal versucht, können Sie Result.retry() von Ihrem Worker zurückgeben. Ihre Arbeit wird dann gemäß einer Backoff-Verzögerung und einer Backoff-Richtlinie neu geplant.

• Mit der Backoff-Verzögerung wird die Mindestwartezeit angegeben, die nach dem ersten Versuch abgewartet werden muss, bevor die Arbeit wiederholt wird. Dieser Wert darf nicht unter 10 Sekunden (oder MIN_BACKOFF_MILLIS) liegen.

• Mit der Backoff-Richtlinie wird festgelegt, wie sich die Backoff-Verzögerung bei nachfolgenden Wiederholungsversuchen im Laufe der Zeit erhöhen soll. WorkManager unterstützt zwei Backoff-Richtlinien: LINEAR und EXPONENTIAL.

Jede Arbeitsanfrage hat eine Backoff-Richtlinie und eine Backoff-Verzögerung. Die Standardrichtlinie ist EXPONENTIAL mit einer Verzögerung von 30 Sekunden. Sie können diese Einstellung jedoch in der Konfiguration der Arbeitsanfrage überschreiben.

Hier ist ein Beispiel für die Anpassung der Backoff-Verzögerung und -Richtlinie.

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

In diesem Beispiel ist die minimale Backoff-Verzögerung auf den zulässigen Mindestwert von 10 Sekunden festgelegt. Da die Richtlinie LINEAR ist, erhöht sich das Wiederholungsintervall mit jedem neuen Versuch um etwa 10 Sekunden. Wenn beispielsweise der erste Durchlauf mit Result.retry() endet, wird nach 10 Sekunden ein neuer Versuch unternommen, gefolgt von 20, 30, 40 Sekunden usw., wenn die Arbeit nach den nachfolgenden Versuchen weiterhin Result.retry() zurückgibt. Wenn die Backoff-Richtlinie auf EXPONENTIAL festgelegt ist, würde die Abfolge der Wiederholungsdauer eher 20, 40, 80 usw. betragen.

Arbeit taggen

Jede Arbeitsanfrage hat eine eindeutige Kennung, mit der sie später identifiziert werden kann, um die Arbeit zu stornieren oder den Fortschritt zu beobachten.

Wenn Sie eine Gruppe von logisch zusammenhängenden Aufgaben haben, kann es auch hilfreich sein, diese Arbeitselemente zu taggen. Mithilfe von Tags können Sie mehrere Arbeitsanfragen gleichzeitig bearbeiten.

Mit WorkManager.cancelAllWorkByTag(String) werden beispielsweise alle Arbeitsanfragen mit einem bestimmten Tag abgebrochen und WorkManager.getWorkInfosByTag(String) gibt eine Liste der WorkInfo-Objekte zurück, mit denen der aktuelle Arbeitsstatus ermittelt werden kann.

Im folgenden Code wird gezeigt, wie Sie Ihrem Projekt ein „cleanup“-Tag hinzufügen:

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

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

Außerdem können einer einzelnen Arbeitsanfrage mehrere Tags hinzugefügt werden. Intern werden diese Tags als Strings gespeichert. Mit WorkInfo.getTags() kannst du die mit der WorkRequest verknüpften Tags abrufen.

Du kannst die Tags der Worker-Klasse über ListenableWorker.getTags() abrufen.

Eingabedaten zuweisen

Für Ihre Arbeit sind möglicherweise Eingabedaten erforderlich. Bei der Verarbeitung des Uploads eines Bildes muss beispielsweise der URI des Bildes als Eingabe hochgeladen werden.

Eingabewerte werden als Schlüssel/Wert-Paare in einem Data-Objekt gespeichert und können für die Arbeitsanfrage festgelegt werden. WorkManager übergibt die Eingabe Data an Ihre Aufgabe, wenn er sie ausführt. Die Klasse Worker kann über den Aufruf von Worker.getInputData() auf die Eingabeargumente zugreifen. Im folgenden Code wird gezeigt, wie Sie eine Worker-Instanz erstellen, für die Eingabedaten erforderlich sind, und wie Sie sie in Ihrer Arbeitsanfrage senden.

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

Ähnlich kann die Klasse Data verwendet werden, um einen Rückgabewert auszugeben. Eingabe- und Ausgabedaten werden im Abschnitt Eingabeparameter und zurückgegebene Werte ausführlicher behandelt.

Nächste Schritte

Auf der Seite Zustände und Beobachtung erfahren Sie mehr über Arbeitszustände und wie Sie den Fortschritt Ihrer Arbeit im Blick behalten.