Arbeitsanfragen definieren

Im Startleitfaden wurde erläutert, wie Sie eine einfache WorkRequest erstellen und in die Warteschlange stellen.

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

• Einmalige und wiederkehrende Aufgaben einplanen
• Arbeitsbeschränkungen festlegen, z. B. WLAN oder Aufladen
• eine minimale Verzögerung bei der Ausführung der Arbeiten zu gewährleisten.
• Wiederholungs- und Backoff-Strategien festlegen
• Eingabedaten an die Arbeit übergeben
• Zusammengehörige Arbeiten mithilfe von Tags gruppieren

Übersicht

Die Arbeit wird in WorkManager über eine WorkRequest definiert. Wenn Sie eine 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. Sie enthält Einschränkungen, die zum Ausführen Ihrer Arbeit erfüllt sein müssen, Planungsinformationen wie Verzögerungen oder Wiederholungsintervalle, Wiederholungskonfigurationen 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 der Name andeutet, ist OneTimeWorkRequest nützlich für die Planung nicht wiederkehrender Aufgaben, während PeriodicWorkRequest besser für die Planung von Arbeiten geeignet ist, die sich in bestimmten Intervallen wiederholen.

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

Schnellarbeit planen

In WorkManager 2.7.0 wurde das Konzept der beschleunigten Arbeit eingeführt. Auf diese Weise kann WorkManager wichtige Aufgaben ausführen, während das System den Zugriff auf Ressourcen besser steuern kann.

Expressarbeiten zeichnet sich durch folgende Merkmale aus:

• Wichtigkeit: Bei beschleunigten Arbeitsschritten handelt es sich um Aufgaben, die für den Nutzer wichtig sind oder vom Nutzer initiiert werden.
• Geschwindigkeit: Beschleunigte Arbeiten eignen 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.
• Energiesparmodus: Einschränkungen bei der Energieverwaltung wie der Energiesparmodus und der Stromsparmodus wirken sich weniger wahrscheinlich auf beschleunigte Arbeiten aus.
• Latenz: Das System führt die beschleunigte Arbeit sofort aus, sofern die aktuelle Arbeitslast dies ermöglicht. Das bedeutet, dass sie latenzempfindlich sind und nicht für eine spätere Ausführung geplant werden können.

Ein möglicher Anwendungsfall für beschleunigte Arbeit könnte in einer Chat-Anwendung sein, wenn der Nutzer eine Nachricht oder ein angehängtes Bild senden möchte. Ebenso kann eine Anwendung, die einen Zahlungs- oder Aboablauf verarbeitet, möglicherweise auch beschleunigte Vorgänge verwenden. Dies liegt daran, dass diese Aufgaben für den Nutzer wichtig sind, im Hintergrund schnell ausgeführt werden, sofort beginnen müssen und auch dann weiter ausgeführt 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. Vielmehr erhält jede Anwendung ein Ausführungszeitkontingent. Wenn Ihre Anwendung die Ausführungszeit erreicht und das zugewiesene Kontingent erreicht, können Sie keine beschleunigte Arbeit mehr ausführen, bis das Kontingent aktualisiert wurde. Dadurch kann Android Ressourcen effektiver zwischen Anwendungen ausgleichen.

Die Ausführungszeit, die einer Anwendung zur Verfügung steht, hängt vom Stand-by-Bucket und der Prozesswichtigkeit ab.

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

Schnellarbeit ausführen

Ab WorkManager 2.7 kann Ihre Anwendung setExpedited() aufrufen, um zu deklarieren, dass WorkRequest mithilfe eines beschleunigten Jobs so schnell wie möglich ausgeführt werden soll. Das folgende Code-Snippet enthält 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 dafür setExpedited() auf. Diese Anfrage wird dann beschleunigt. Wenn das Kontingent es zulässt, wird sie sofort im Hintergrund ausgeführt. Wenn das Kontingent bereits ausgeschöpft ist, gibt der Parameter OutOfQuotaPolicy an, dass die Anfrage wie gewohnt und ohne Beschleunigung ausgeführt werden soll.

Abwärtskompatibilität und Dienste im Vordergrund

Um die Abwärtskompatibilität für beschleunigte Jobs zu wahren, 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 die Aufgabe als beschleunigter Job ausgeführt werden soll.

Bei einer Ausrichtung auf Android 12 oder höher stehen Ihnen Dienste im Vordergrund über die entsprechende setForeground-Methode weiterhin zur Verfügung.

Mitarbeiter

Die Mitarbeitenden wissen nicht, ob die Arbeit, die sie erledigen, beschleunigt wird oder nicht. Worker können jedoch unter einigen Android-Versionen eine Benachrichtigung anzeigen lassen, 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 für Sie anzeigen kann.

CoroutineWorker

Wenn du CoroutineWorker verwendest, musst du getForegroundInfo() implementieren. Anschließend übergeben Sie sie in doWork() an setForeground(). Dadurch wird die Benachrichtigung in Android-Versionen vor 12 erstellt.

Hier 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 beschleunigter Arbeit geschehen soll, wenn Ihre Anwendung ihr Ausführungskontingent erreicht hat. Zum Fortfahren kannst du setExpedited() übergeben:

• OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST, was dazu führt, dass der Job als normale Arbeitsanfrage ausgeführt wird. Das obige Snippet veranschaulicht dies.
• OutOfQuotaPolicy.DROP_WORK_REQUEST: Damit wird die Anfrage abgebrochen, wenn das Kontingent nicht ausreicht.

Beispiel-App

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

Aufgeschobene beschleunigte Arbeit

Das System versucht, einen bestimmten beschleunigten Job so schnell wie möglich nach dem Aufruf des Jobs auszuführen. Wie bei anderen Arten von Jobs kann das System jedoch den Start neuer beschleunigter Aufgaben verschieben, wie in den folgenden Fällen:

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

Regelmäßige Arbeiten einplanen

Es kann von Zeit zu Zeit erforderlich sein, dass bestimmte Aufgaben in Ihrer App regelmäßig ausgeführt werden. Beispielsweise können Sie Ihre Daten regelmäßig sichern, aktuelle Inhalte in Ihre Anwendung herunterladen oder Protokolle auf einen Server hochladen.

So verwenden Sie das PeriodicWorkRequest, um ein WorkRequest-Objekt zu erstellen, 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 mit einem Intervall von einer Stunde geplant.

Der Intervallzeitraum ist definiert als die Mindestzeit zwischen Wiederholungen. Die genaue Zeit, zu der der Worker ausgeführt wird, hängt von den Einschränkungen ab, die Sie in Ihrem WorkRequest-Objekt verwenden, sowie von den vom System ausgeführten Optimierungen.

Flexible Ausführungsintervalle

Wenn die Art Ihrer Arbeit den Ausführungszeitpunkt beeinträchtigt, können Sie den PeriodicWorkRequest so konfigurieren, dass er innerhalb jedes Intervallzeitraums innerhalb eines flexiblen Zeitraums ausgeführt wird, wie in Abbildung 1 dargestellt.

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

Um regelmäßige Arbeit mit einem flexiblen Zeitraum zu definieren, übergeben Sie beim Erstellen von PeriodicWorkRequest ein flexInterval zusammen mit dem repeatInterval. Der Flex-Zeitraum beginnt um repeatInterval - flexInterval und endet am Ende des Intervalls.

Im Folgenden finden Sie ein Beispiel für regelmäßige Arbeit, die in den letzten 15 Minuten einer 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 Flex-Intervall muss größer oder gleich PeriodicWorkRequest.MIN_PERIODIC_FLEX_MILLIS sein.

Auswirkungen von Einschränkungen auf regelmäßige Arbeiten

Sie können Einschränkungen auf regelmäßige Arbeiten anwenden. Sie können Ihrer Arbeitsanfrage beispielsweise eine Einschränkung hinzufügen, sodass die Arbeit nur dann ausgeführt wird, wenn das Gerät des Nutzers aufgeladen wird. In diesem Fall wird PeriodicWorkRequest erst ausgeführt, wenn die Bedingung erfüllt ist, selbst wenn das definierte Wiederholungsintervall verstrichen ist. Dies kann dazu führen, dass eine bestimmte Ausführung Ihrer Arbeit verzögert wird oder sogar übersprungen wird, wenn die Bedingungen innerhalb des Ausführungsintervalls nicht erfüllt sind.

Arbeitsbedingte Einschränkungen

Einschränkungen stellen sicher, dass die Arbeit aufgeschoben wird, bis die optimalen Bedingungen erfüllt sind. Die folgenden Einschränkungen sind für WorkManager verfügbar.

Um eine Reihe von Einschränkungen zu erstellen und sie mit Aufgaben zu verknüpfen, erstellen Sie eine Constraints-Instanz mit Contraints.Builder() und weisen sie Ihrer WorkRequest.Builder() zu.

Mit dem folgenden Code wird beispielsweise eine Arbeitsanfrage erstellt, die nur ausgeführt wird, wenn das Gerät des Nutzers sowohl geladen wird als auch mit einem 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 sind, wird Ihre Arbeit nur ausgeführt, wenn alle Einschränkungen erfüllt sind.

Falls eine Einschränkung nicht erfüllt wird, während Ihre Arbeit ausgeführt wird, wird der Worker von WorkManager angehalten. Wenn alle Einschränkungen erfüllt sind, wird der Vorgang wiederholt.

Verspätete Arbeit

Falls für Ihre Arbeit keine Einschränkungen gelten oder alle Einschränkungen beim Einreihen der Arbeit in die Warteschlange erfüllt sind, kann das System die Arbeit sofort ausführen. Wenn Sie nicht möchten, dass die Arbeit sofort ausgeführt wird, können Sie angeben, dass sie nach einer minimalen anfänglichen Verzögerung gestartet werden soll.

Im folgenden Beispiel wird gezeigt, wie Sie Ihre Arbeit so einstellen, dass sie mindestens 10 Minuten nach dem Einreihen 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 Sie eine anfängliche Verzögerung für ein OneTimeWorkRequest festlegen. Sie können aber auch eine anfängliche Verzögerung für ein PeriodicWorkRequest festlegen. In diesem Fall würde nur die erste Ausführung Ihrer regelmäßigen Arbeit verzögert werden.

Wiederholungs- und Backoff-Richtlinie

Wenn Sie möchten, dass WorkManager Ihre Arbeit wiederholt, können Sie Result.retry() von Ihrem Worker zurückgeben. Ihre Arbeit wird dann entsprechend einer Backoff-Verzögerung und einer Backoff-Richtlinie verschoben.

• Die Backoff-Verzögerung gibt die Mindestzeit an, die gewartet werden muss, bevor der Vorgang nach dem ersten Versuch wiederholt wird. Dieser Wert darf nicht kleiner als 10 Sekunden (oder MIN_BACKOFF_MILLIS) sein.

• Die Backoff-Richtlinie definiert, wie die Backoff-Verzögerung bei nachfolgenden Wiederholungsversuchen im Laufe der Zeit zunimmt. WorkManager unterstützt zwei Backoff-Richtlinien: LINEAR und EXPONENTIAL.

Für jede Arbeitsanfrage gelten eine Backoff-Richtlinie und eine Backoff-Verzögerung. Die Standardrichtlinie ist EXPONENTIAL mit einer Verzögerung von 30 Sekunden. Sie können diese jedoch in der Konfiguration Ihrer 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 minimalen zulässigen Wert von 10 Sekunden festgelegt. Da die Richtlinie LINEAR ist, verlängert sich das Wiederholungsintervall bei jedem neuen Versuch um etwa 10 Sekunden. Beispielsweise wird die erste Ausführung mit Result.retry() nach 10 Sekunden noch einmal versucht, gefolgt von 20, 30, 40 usw., wenn die Arbeit auch nach weiteren Versuchen weiterhin Result.retry() zurückgibt. Wenn die Backoff-Richtlinie auf EXPONENTIAL gesetzt wäre, wäre die Reihenfolge der Wiederholungsdauer näher an 20, 40, 80 usw.

Arbeit taggen

Jede Arbeitsanfrage hat eine eindeutige Kennung, über die sie später identifiziert werden kann, um die Arbeit abgebrochen oder ihren Fortschritt zu beobachten.

Bei einer Gruppe logisch zusammengehöriger Aufgaben kann es auch hilfreich sein, diese Arbeitselemente mit Tags zu versehen. Durch das Tagging können Sie eine Gruppe von Arbeitsanfragen gemeinsam bearbeiten.

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

Der folgende Code zeigt, wie Sie Ihrer Arbeit 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 ein Satz von Strings gespeichert. Mit WorkInfo.getTags() können Sie die mit WorkRequest verknüpften Tags abrufen.

Sie können den Satz von Tags aus der Worker-Klasse über ListenableWorker.getTags() abrufen.

Eingabedaten zuweisen

Für Ihre Arbeit sind möglicherweise Eingabedaten erforderlich. Für Aufgaben, die das Hochladen eines Bildes verarbeiten, kann beispielsweise der URI des Bilds 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 sendet die Eingabe-Data an Ihre Arbeit, wenn die Arbeit ausgeführt wird. Die Klasse Worker kann durch Aufrufen von Worker.getInputData() auf die Eingabeargumente zugreifen. Der folgende Code zeigt, wie Sie eine Worker-Instanz erstellen, die Eingabedaten erfordert, und wie Sie diese 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();

In ähnlicher Weise 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 Status und Beobachtung erfahren Sie mehr über Arbeitsstatus und wie Sie den Fortschritt Ihrer Arbeit überwachen können.