用户发起的数据传输

如果您需要执行可能需要很长时间的数据传输，您可以创建一个 JobScheduler 作业并将其标识为用户发起的数据传输 (UIDT) 作业。UIDT 作业适用于由设备用户发起的较长时间的数据传输，例如从远程服务器下载文件。UIDT 作业是在 Android 14（API 级别 34）中引入的。

用户发起的数据传输作业由用户启动。这些作业需要通知，立即启动，并且可能能够在系统条件允许的情况下运行较长时间。您可以同时运行多个用户发起的数据传输作业。

用户发起的作业必须在应用对用户可见时（或在允许的条件之一中）安排。在满足所有约束条件后，操作系统可以执行用户发起的作业，但须遵守系统健康限制。系统还可以使用提供的估计有效负载大小来确定作业执行的时长。

安排用户发起的数据传输作业

要运行用户发起的传输作业，请执行以下操作

  1. 确保您的应用已在其清单中声明了 JobService 和相关权限

    <service android:name="com.example.app.CustomTransferService"
        android:permission="android.permission.BIND_JOB_SERVICE"
        android:exported="false">
        ...
</service>

    此外，为您的数据传输定义 JobService 的具体子类

    Kotlin

    class CustomTransferService : JobService() {
  ...
}

    Java

    class CustomTransferService extends JobService() {

    ....

}

  2. 在清单中声明 RUN_USER_INITIATED_JOBS 权限

    <manifest ...>
    <uses-permission android:name="android.permission.RUN_USER_INITIATED_JOBS" />
    <application ...>
        ...
    </application>
</manifest>

  3. 在构建 JobInfo 对象时，调用 setUserInitiated() 方法。（此方法从 Android 14 开始可用。）我们还建议您通过在创建作业时调用 setEstimatedNetworkBytes() 来提供有效负载大小估算。

    Kotlin

    val networkRequestBuilder = NetworkRequest.Builder()
        // Add or remove capabilities based on your requirements.
        // For example, this code specifies that the job won't run
        // unless there's a connection to the internet (not just a local
        // network), and the connection doesn't charge per-byte.
        .addCapability(NET_CAPABILITY_INTERNET)
        .addCapability(NET_CAPABILITY_NOT_METERED)
        .build()

val jobInfo = JobInfo.Builder(jobId,
              ComponentName(mContext, CustomTransferService::class.java))
        // ...
        .setUserInitiated(true)
        .setRequiredNetwork(networkRequestBuilder)
        // Provide your estimate of the network traffic here
        .setEstimatedNetworkBytes(1024 * 1024 * 1024)
        // ...
        .build()

    Java

    NetworkRequest networkRequest = new NetworkRequest.Builder()
    // Add or remove capabilities based on your requirements.
    // For example, this code specifies that the job won't run
    // unless there's a connection to the internet (not just a local
    // network), and the connection doesn't charge per-byte.
    .addCapability(NET_CAPABILITY_INTERNET)
    .addCapability(NET_CAPABILITY_NOT_METERED)
    .build();

JobInfo jobInfo = JobInfo.Builder(jobId,
        new ComponentName(mContext, DownloadTransferService.class))
    // ...
    .setUserInitiated(true)
    .setRequiredNetwork(networkRequest)
    // Provide your estimate of the network traffic here
    .setEstimatedNetworkBytes(1024 * 1024 * 1024)
    // ...
    .build();

  4. 在执行作业期间，在 JobService 对象上调用 setNotification()。调用 setNotification() 会让用户知道作业正在运行，无论是在任务管理器中还是在状态栏通知区域中。

    执行完成后，调用 jobFinished() 向系统发出信号，表明作业已完成或应重新安排作业。

    Kotlin

    class DownloadTransferService: JobService() {
    private val scope = CoroutineScope(Dispatchers.IO)

    @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
    override fun onStartJob(params: JobParameters): Boolean {
        val notification = Notification.Builder(applicationContext,
                              NOTIFICATION_CHANNEL_ID)
            .setContentTitle("My user-initiated data transfer job")
            .setSmallIcon(android.R.mipmap.myicon)
            .setContentText("Job is running")
            .build()

        setNotification(params, notification.id, notification,
                JobService.JOB_END_NOTIFICATION_POLICY_DETACH)
        // Execute the work associated with this job asynchronously.
        scope.launch {
            doDownload(params)
        }
        return true
    }

    private suspend fun doDownload(params: JobParameters) {
        // Run the relevant async download task, then call
        // jobFinished once the task is completed.
        jobFinished(params, false)
    }

    // Called when the system stops the job.
    override fun onStopJob(params: JobParameters?): Boolean {
        // Asynchronously record job-related data, such as the
        // stop reason.
        return true // or return false if job should end entirely
    }
}

    Java

    class DownloadTransferService extends JobService{
    @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
    @Override
    public boolean onStartJob(JobParameters params) {
        Notification notification = Notification.Builder(getBaseContext(),
                                        NOTIFICATION_CHANNEL_ID)
                .setContentTitle("My user-initiated data transfer job")
                .setSmallIcon(android.R.mipmap.myicon)
                .setContentText("Job is running")
                .build();

        setNotification(params, notification.id, notification,
                          JobService.JOB_END_NOTIFICATION_POLICY_DETACH)
        // Execute the work associated with this job asynchronously.
        new Thread(() -> doDownload(params)).start();
        return true;
    }

    private void doDownload(JobParameters params) {
        // Run the relevant async download task, then call
        // jobFinished once the task is completed.
        jobFinished(params, false);
    }

    // Called when the system stops the job.
    @Override
    public boolean onStopJob(JobParameters params) {
        // Asynchronously record job-related data, such as the
        // stop reason.
        return true; // or return false if job should end entirely
    }
}

  5. 定期更新通知，以使用户了解作业的状态和进度。如果您无法在安排作业之前确定传输大小，或者需要更新估计的传输大小，请使用新的 API updateEstimatedNetworkBytes() 在已知传输大小后更新它。

建议

要有效地运行 UIDT 作业，请执行以下操作

  1. 明确定义网络约束和作业执行约束，以指定应何时执行作业。

  2. 在 onStartJob() 中异步执行任务；例如，您可以使用 协程 来执行此操作。如果您没有异步运行任务，则该工作将在主线程上运行并可能阻塞它，这会导致 ANR。

  3. 为避免作业运行时间过长，在传输完成后（无论成功与否）调用 jobFinished()。这样，作业就不会运行时间过长。要了解作业停止的原因，请实现 onStopJob() 回调方法并调用 JobParameters.getStopReason()。

向后兼容性

目前没有支持 UIDT 作业的 Jetpack 库。因此，我们建议您使用验证您是否在 Android 14 或更高版本上运行的代码来控制您的更改。在较低版本的 Android 上，您可以使用 WorkManager 的前台服务实现 作为备用方法。

这是一个检查相应系统版本的代码示例

Kotlin

fun beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadUIDTJob(context)
    } else {
        scheduleDownloadFGSWorker(context)
    }
}

private fun scheduleDownloadUIDTJob(context: Context) {
    // build jobInfo
    val jobScheduler: JobScheduler =
        context.getSystemService(Context.JOB_SCHEDULER_SERVICE) as JobScheduler
    jobScheduler.schedule(jobInfo)
}

private fun scheduleDownloadFGSWorker(context: Context) {
    val myWorkRequest = OneTimeWorkRequest.from(DownloadWorker::class.java)
    WorkManager.getInstance(context).enqueue(myWorkRequest)
}

Java

public void beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadUIDTJob(context);
    } else {
        scheduleDownloadFGSWorker(context);
    }
}

private void scheduleDownloadUIDTJob(Context context) {
    // build jobInfo
    JobScheduler jobScheduler =
            (JobScheduler) context.getSystemService(Context.JOB_SCHEDULER_SERVICE);
    jobScheduler.schedule(jobInfo);
}

private void scheduleDownloadFGSWorker(Context context) {
    OneTimeWorkRequest myWorkRequest = OneTimeWorkRequest.from(DownloadWorker.class);
    WorkManager.getInstance(context).enqueue(myWorkRequest)
}

停止 UIDT 作业

用户和系统都可以停止用户发起的传输作业。

由用户从任务管理器停止

用户可以停止出现在 任务管理器 中的用户发起的数据传输作业。

在用户按下停止的那一刻，系统将执行以下操作

  • 立即终止应用的进程，包括所有其他正在运行的作业或前台服务。
  • 不会为任何正在运行的作业调用onStopJob()。
  • 阻止用户可见的作业重新调度。

出于这些原因，建议在为作业发布的通知中提供控件，以允许优雅地停止和重新调度作业。

请注意，在特殊情况下，停止按钮不会出现在任务管理器中作业旁边，或者作业根本不会显示在任务管理器中。

由系统

与常规作业不同，用户发起的的数据传输作业不受应用待机存储区配额的影响。但是，如果发生以下任何情况，系统仍会停止作业

  • 开发人员定义的约束条件不再满足。
  • 系统确定作业的运行时间已超过完成数据传输任务所需的时间。
  • 系统需要优先考虑系统健康状况，并由于热状态升高而停止作业。
  • 由于设备内存不足导致应用进程被终止。

当作业因除设备内存不足以外的其他原因被系统停止时，系统会调用onStopJob()，并且系统会在系统认为最佳的时间重试该作业。请确保您的应用即使在未调用onStopJob()的情况下也能持久保存数据传输状态，并且您的应用可以在再次调用onStartJob()时恢复此状态。

允许调度用户发起的的数据传输作业的条件

应用只有在应用位于可见窗口中，或满足某些条件时才能启动用户发起的的数据传输作业

  • 如果应用可以从后台启动活动，则它也可以从后台启动用户发起的的数据传输作业。
  • 如果应用在最近屏幕上现有任务的后堆栈中有一个活动，这本身并不允许用户发起的的数据传输作业运行。

如果作业计划在不满足必要条件的时间运行，则作业将失败并返回RESULT_FAILURE错误代码。

允许用户发起的的数据传输作业的约束条件

为了支持作业在最佳时间点运行，Android 提供了为每种作业类型分配约束条件的功能。这些约束条件从 Android 13 开始可用。

注意：下表仅比较每种作业类型之间不同的约束条件。有关所有约束条件，请参阅JobScheduler 开发人员页面或工作约束条件。

下表显示了支持给定作业约束条件的不同作业类型，以及 WorkManager 支持的作业约束条件集。使用表格之前的搜索栏按作业约束条件方法的名称筛选表格。

这些是用户发起的的数据传输作业允许的约束条件

  • setBackoffCriteria(JobInfo.BACKOFF_POLICY_EXPONENTIAL)
  • setClipData()
  • setEstimatedNetworkBytes()
  • setMinimumNetworkChunkBytes()
  • setPersisted()
  • setNamespace()
  • setRequiredNetwork()
  • setRequiredNetworkType()
  • setRequiresBatteryNotLow()
  • setRequiresCharging()
  • setRequiresStorageNotLow()

测试

以下列表显示了手动测试应用作业的一些步骤

  • 要获取作业 ID，请获取作业构建时定义的值。

  • 要立即运行作业或重试已停止的作业，请在终端窗口中运行以下命令

    adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

  • 要模拟系统强制停止作业（由于系统健康状况或超出配额条件），请在终端窗口中运行以下命令

    adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID