使用者啟動的資料移轉

如要執行可能需要長時間的資料轉移作業，可以建立 JobScheduler 工作，並將其識別為使用者啟動的資料轉移 (UIDT) 工作。UIDT 工作適用於裝置使用者啟動的長時間資料轉移作業，例如從遠端伺服器下載檔案。Android 14 (API 級別 34) 導入了 UIDT 工作。

顧名思義，使用者啟動的資料移轉工作是由使用者所發起的。這類工作會要求傳送通知並且要立即開始執行，如果系統條件允許，還可能會長時間執行。您可以同時執行多項使用者啟動的資料移轉工作。

當使用者具備應用程式的瀏覽權限時 (或符合任一許可條件)，則必須為使用者啟動的工作進行排程。滿足所有限制後，作業系統就能執行使用者啟動的工作，具體情況取決於系統健康狀態限制。此外，系統也能根據所提供的預估酬載大小，判斷執行工作的時間長度。

排定使用者啟動的資料移轉作業

如要執行使用者啟動的資料移轉作業，請按照下列步驟操作：

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 的前景服務實作做為備用方法。

以下是檢查適當系統版本的程式碼範例：

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)
}

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

另請參閱

• 背景工作總覽
• 資料移轉背景工作選項

其他資源

如要進一步瞭解使用者發起的資料轉移作業，請參閱下列其他資源：

• 使用者啟動的資料轉移整合案例研究：Google 地圖使用使用者啟動的資料轉移 API，將下載可靠性提升 10%