更新已加入队列的工作

WorkManager 允许您在将 WorkRequest 加入队列后对其进行更新。这在大型应用中通常是必要的,因为这些应用会频繁更改约束条件或需要实时更新其 worker。从 WorkManager 2.8.0 版开始,updateWork() API 是实现此目的的方法。

借助 updateWork() 方法,您可以动态更改 WorkRequest 的某些方面,而无需手动取消并使新作业入队。这大大简化了开发流程。

避免取消工作

通常,您应避免取消现有 WorkRequest 并将新 WorkRequest 加入队列。这样做可能会导致应用重复执行某些任务,并且可能需要您编写大量额外的代码。

请考虑以下示例,了解取消 WorkRequest 可能会导致哪些问题:

  • 后端请求:如果您在 Worker 计算要发送到服务器的载荷时取消该请求,则新的 Worker 需要重新开始并重新计算可能开销很大的载荷。
  • 调度:如果您取消了 PeriodicWorkRequest,并且希望新的 PeriodicWorkRequest 按相同的时间表执行,则需要计算时间偏移值,以确保新的执行时间与之前的工作请求保持一致。

借助 updateWork() API,您可以更新工作请求的约束条件和其他参数,而无需取消和将新请求加入队列。

何时取消工作

在某些情况下,您应该直接取消 WorkRequest,而不是调用 updateWork()。如果您想更改已加入队列的工作的基本性质,则应执行此操作。

何时更新工作

假设有一款照片应用,每天都会备份用户的照片。它已将 PeriodicWorkRequest 加入队列来执行此操作。WorkRequest 具有一些限制,要求设备处于充电状态并连接到 Wi-Fi。

不过,该用户每天只使用快充为设备充电 20 分钟。在这种情况下,应用可能需要更新 WorkRequest 以放宽充电限制,以便即使设备未充满电,也能上传照片。

在这种情况下,您可以使用 updateWork() 方法更新工作请求的约束条件。

如何更新作业

updateWork() 方法提供了一种更新现有 WorkRequest 的简单方法,而无需取消现有 并将新 加入队列。

如需使用更新已加入队列的工作,请按以下步骤操作:

  1. 获取已加入队列的工作的现有 ID:获取您要更新的 WorkRequest 的 ID。您可以使用任何 getWorkInfo API 检索此 ID,也可以在将初始 WorkRequest 加入队列之前,通过手动保留该 ID 以便日后使用公共属性 WorkRequest.id 进行检索。
  2. 创建新的 WorkRequest:创建新的 WorkRequest,并使用 WorkRequest.Builder.setID() 将其 ID 设置为与现有 WorkRequest 的 ID 匹配。
  3. 设置约束条件:使用 WorkRequest.Builder.setConstraints() 传递 WorkManager 新约束条件。
  4. 调用 updateWork:将新的 WorkRequest 传递给 updateWork()。

更新工作示例

以下是 Kotlin 中的示例代码段,演示了如何使用 updateWork() 方法更改用于上传照片的 WorkRequest 的电池约束条件:

suspend fun updatePhotoUploadWork() {
    // Get instance of WorkManager.
    val workManager = WorkManager.getInstance(context)

    // Retrieve the work request ID. In this example, the work being updated is unique
    // work so we can retrieve the ID using the unique work name.
    val photoUploadWorkInfoList = workManager.getWorkInfosForUniqueWork(
        PHOTO_UPLOAD_WORK_NAME
    ).await()

    val existingWorkRequestId = photoUploadWorkInfoList.firstOrNull()?.id ?: return

    // Update the constraints of the WorkRequest to not require a charging device.
    val newConstraints = Constraints.Builder()
        // Add other constraints as required here.
        .setRequiresCharging(false)
        .build()

    // Create new WorkRequest from existing Worker, new constraints, and the id of the old WorkRequest.
    val updatedWorkRequest: WorkRequest =
        OneTimeWorkRequestBuilder<MyWorker>()
            .setConstraints(newConstraints)
            .setId(existingWorkRequestId)
            .build()

    // Pass the new WorkRequest to updateWork().
    workManager.updateWork(updatedWorkRequest)
}

处理结果

updateWork() 会返回 ListenableFuture<UpdateResult>。给定的 UpdateResult 可以具有多个值中的一个,这些值概述了 WorkManager 是否能够应用您的更改。它还会指明何时能够应用更改。

如需了解详情,请参阅 updateWork()和 UpdateResult参考文档。

使用代次跟踪工作

每次更新 WorkRequest 时,其代都会递增 1。这样,您就可以准确跟踪当前已加入队列的 WorkRequest。 在观察、跟踪和测试工作请求时,代次可为您提供更多控制。

如需获取 WorkRequest 的世代,请按以下步骤操作:

  1. WorkInfo:调用 WorkManager.getWorkInfoById() 以检索与您的 WorkRequest 对应的 WorkInfo 实例。
  2. getGeneration:对 WorkInfo 的实例调用 getGeneration()。返回的 Int 对应于 WorkRequest 的代。
    • 请注意,没有代次字段或属性,只有 WorkInfo.getGeneration() 方法。

曲目生成示例

以下是上述工作流的示例实现,用于检索 WorkRequest 的生成。

// Get instance of WorkManager.
val workManager = WorkManager.getInstance(context)

// Retrieve WorkInfo instance.
val workInfo = workManager.getWorkInfoById(oldWorkRequestId)

// Call getGeneration to retrieve the generation.
val generation = workInfo.getGeneration()

更新作品的政策

以前,更新定期工作的推荐解决方案是使用政策 ExistingPeriodicWorkPolicy.REPLACE 将 PeriodicWorkRequest 加入队列。如果存在具有相同唯一 id 的待处理 PeriodicWorkRequest,新的工作请求会取消并删除该待处理工作。此政策现已弃用,取而代之的是使用 ExistingPeriodicWorkPolicy.UPDATE 的工作流。

例如,将 enqueueUniquePeriodicWork 与 PeriodicWorkRequest 搭配使用时,您可以使用 ExistingPeriodicWorkPolicy.UPDATE 政策初始化新的 PeriodicWorkRequest。如果存在具有相同唯一名称的待处理 PeriodicWorkRequest,WorkManager 会将其更新为新规范。按照此工作流,无需使用 updateWork()。