用户发起的数据传输

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

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

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

计划用户发起的数据传输作业

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

确保您的应用已在其清单中声明了 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() {

    ....

}

在清单中声明 RUN_USER_INITIATED_JOBS 权限。

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

在构建 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();

在执行作业期间，在 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
    }
}

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

建议

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

明确定义网络约束和作业执行约束，以指定何时应执行作业。
在onStartJob()中异步执行任务；例如，您可以使用协程来实现。如果您没有异步运行任务，则工作将在主线程上运行并可能阻塞它，这会导致应用程序无响应 (ANR)。
为了避免作业运行时间过长，在传输完成时（无论成功还是失败）调用jobFinished()。这样，作业就不会运行时间过长。要了解作业停止的原因，请实现onStopJob()回调方法并调用JobParameters.getStopReason()。

向后兼容性

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

以下是一个检查适当系统版本的代码示例

Kotlin

fun beginTask() {
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleDownloadFGSWorker(context)
    } else {
        scheduleDownloadUIDTJob(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) {
        scheduleDownloadFGSWorker(context);
    } else {
        scheduleDownloadUIDTJob(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
```

另请参阅

其他资源

有关用户发起的资料传输的更多信息，请参阅以下其他资源

UIDT 集成案例研究：Google 地图通过使用用户发起的资料传输 API 将下载可靠性提高了 10％