Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用者啟動的資料移轉

如果您需要执行可能需要很长时间的数据传输，可以创建一个 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, 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, CustomTransferService.class))
    // ...
    .setUserInitiated(true)
    .setRequiredNetwork(networkRequest)
    // Provide your estimate of the network traffic here
    .setEstimatedNetworkBytes(1024 * 1024 * 1024, 1024 * 1024 * 1024)
    // ...
    .build();

執行工作時，請在 JobService 物件上呼叫 setNotification()。呼叫 setNotification() 會讓使用者知道工作正在執行，無論是在工作管理員還是狀態列通知區域中。

執行作業完成後，請呼叫 jobFinished() 以告知系統工作已經完成，或應重新為工作排程。

Kotlin

class CustomTransferService: 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 CustomTransferService 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 錯誤代碼。