Kullanıcı tarafından başlatılan veri aktarımı

Uzun sürebilecek bir veri aktarımı yapmanız gerekiyorsa JobScheduler işi oluşturabilir ve bunu kullanıcı tarafından başlatılan veri aktarımı (UIDT) işi olarak tanımlayabilirsiniz. UIDT işleri, cihaz kullanıcısı tarafından başlatılan uzun süreli veri aktarımları (ör. uzaktaki bir sunucudan dosya indirme) için tasarlanmıştır. UIDT görevleri, Android 14 (API düzeyi 34) ile kullanıma sunuldu.

Kullanıcı tarafından başlatılan veri aktarımı işleri, kullanıcı tarafından başlatılır. Bu işlerin bildirim görüntülemesi ve hemen başlaması gerekir. Bu işler, sistem koşulları izin verirse uzun süre boyunca çalıştırılabilir. Kullanıcı tarafından başlatılan birden fazla veri aktarımı işini eşzamanlı olarak çalıştırabilirsiniz.

Kullanıcı tarafından başlatılan işler, uygulamanın kullanıcı tarafından görülebildiği zaman (veya izin verilen koşullardan birinde) planlanmalıdır. Kullanıcı tarafından başlatılan işler, tüm koşullar karşılandıktan sonra sistem sağlığı kısıtlamalarına tabi olarak işletim sistemi tarafından yürütülebilir. Sistem, işin ne kadar süre boyunca yürütüleceğini belirlemek için sağlanan tahmini yük boyutunu da kullanabilir.

Not: Kısa süreli ve kesintiye uğratılabilir ağ veri aktarımı kullanım alanları için şu anda WorkManager'ı kullanıyorsanız kullanıcı tarafından başlatılan veri aktarım işlerine geçmek yerine WorkManager'ı kullanmaya devam etmenizi öneririz. UIDT'yi kullanıp kullanmamanız gerektiğini daha iyi anlamak için Veri aktarımı arka plan görevi seçenekleri dokümanına bakın.

Kullanıcı tarafından başlatılan veri aktarımı işlerini planlama

Kullanıcı tarafından başlatılan bir veri aktarımı işini çalıştırmak için aşağıdakileri yapın:

1. Uygulamanızın manifest dosyasında JobService ve ilişkili izinlerin beyan edildiğinden emin olun:

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

   Ayrıca, veri aktarımınız için JobService öğesinin somut bir alt sınıfını tanımlayın:

   Kotlin

   class CustomTransferService : JobService() {
     ...
   }

   Java

   class CustomTransferService extends JobService() {
   
       ....
   
   }

2. Manifest dosyasında RUN_USER_INITIATED_JOBS iznini beyan edin:

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

3. setUserInitiated() yöntemini bir JobInfo nesnesi oluştururken çağırın. (Bu yöntem, Android 14'ten itibaren kullanılabilir.) Ayrıca, işinizi oluştururken setEstimatedNetworkBytes() işlevini çağırarak bir yük boyutu tahmini sunmanızı öneririz.

   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, CustomTransferService.class))
       // ...
       .setUserInitiated(true)
       .setRequiredNetwork(networkRequest)
       // Provide your estimate of the network traffic here
       .setEstimatedNetworkBytes(1024 * 1024 * 1024)
       // ...
       .build();

4. İş yürütülürken JobService nesnesinde setNotification() işlevini çağırın. Calling setNotification(), hem Görev Yöneticisi'nde hem de durum çubuğu bildirim alanında kullanıcının işin çalıştığından haberdar olmasını sağlar.

   Yürütme tamamlandığında, işin tamamlandığını veya yeniden planlanması gerektiğini sisteme bildirmek için jobFinished() işlevini çağırın.

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

5. Kullanıcıyı işin durumu ve ilerleme durumu hakkında bilgilendirmek için bildirimi düzenli olarak güncelleyin. İşi planlamadan önce aktarım boyutunu belirleyemiyorsanız veya tahmini aktarım boyutunu güncellemeniz gerekiyorsa aktarım boyutu bilindikten sonra güncellemek için yeni API'yi (updateEstimatedNetworkBytes()) kullanın.

Öneriler

UIDT işlerini etkili bir şekilde çalıştırmak için aşağıdakileri yapın:

1. İşin ne zaman yürütülmesi gerektiğini belirtmek için ağ kısıtlamalarını ve iş yürütme kısıtlamalarını net bir şekilde tanımlayın.

2. Görevi onStartJob() içinde eşzamansız olarak yürütün. Örneğin, bunu eş yordam kullanarak yapabilirsiniz. Görevi eşzamanlı olarak çalıştırmazsanız çalışma ana iş parçacığında çalışır ve onu engelleyebilir. Bu durum ANR'ye neden olabilir.

3. İşin gereğinden uzun süre çalışmasını önlemek için aktarım başarılı olsa da olmasa da tamamlandığında jobFinished() işlevini çağırın. Böylece iş, gerekenden daha uzun sürmez. Bir işin neden durdurulduğunu öğrenmek için onStopJob() geri çağırma yöntemini uygulayın ve JobParameters.getStopReason() yöntemini çağırın.

Geriye dönük uyumluluk

Şu anda UIDT işlerini destekleyen bir Jetpack kitaplığı yoktur. Bu nedenle, değişikliğinizi Android 14 veya daha yeni bir sürümde çalıştığınızı doğrulayan bir kodla sınırlamanızı öneririz. Daha düşük Android sürümlerinde, alternatif bir yaklaşım olarak WorkManager'ın ön plan hizmeti uygulamasını kullanabilirsiniz.

Aşağıda, uygun sistem sürümünü kontrol eden bir kod örneği verilmiştir:

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 işlerini durdurma

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

Kullanıcı tarafından, görev yöneticisinden

The user can stop a user-initiated data transfer job that appears in the Task Manager.

At the moment that the user presses Stop, the system does the following:

• Terminates your app's process immediately, including all other jobs or foreground services running.
• Doesn't call onStopJob() for any running jobs.
• Prevents user-visible jobs from being rescheduled.

For these reasons, it's recommended to provide controls in the notification posted for the job to allow gracefully stopping and rescheduling the job.

Note that, under special circumstances, the Stop button doesn't appear next to the job in the Task Manager, or the job isn't shown in the Task Manager at all.

Sistem tarafından

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

• 不再满足开发者定义的约束条件。
• 系统确定该作业的运行时间超出了完成数据传输任务所需的时间。
• 系统需要优先考虑系统运行状况，并因发热程度上升而停止作业。
• 应用进程因设备内存不足而被终止。

如果系统因设备内存不足以外的原因停止作业，系统会调用 onStopJob()，并在系统认为最佳的时间重试作业。确保您的应用可以保留数据传输状态（即使未调用 onStopJob()），并且您的应用可以在再次调用 onStartJob() 时恢复此状态。

Kullanıcı tarafından başlatılan veri aktarımı işlerinin planlanmasına izin verilen koşullar

Uygulamalar, yalnızca görünür penceredeyse veya belirli koşullar karşılanıyorsa kullanıcı tarafından başlatılan bir veri aktarımı işi başlatabilir:

• Bir uygulama arka plandan etkinlik başlatabiliyorsa kullanıcı tarafından başlatılan veri aktarımı işlerini de arka plandan başlatabilir.
• Bir uygulamanın En son ekranındaki mevcut bir görevin arka yığınında etkinliği varsa bu durum tek başına kullanıcı tarafından başlatılan veri aktarma işinin çalışmasına izin vermez.

Not: UIDT işini arka plandan başlatma koşullarının ön plan hizmetlerini arka plandan başlatmasına izin veren muafiyetler ile aynı olmadığı

unutulmamalıdır.

Görev, gerekli koşulların karşılanmadığı bir zamanda çalışacak şekilde planlanırsa başarısız olur ve RESULT_FAILURE hata kodu döndürür.

Kullanıcı tarafından başlatılan veri aktarımı işlerine izin verilen kısıtlamalar

Android, en uygun noktalarda çalışan işleri desteklemek için her iş türüne kısıtlamalar atama olanağı sunar. Bu kısıtlamalar Android 13'ten itibaren kullanılabilir.

Not: Aşağıdaki tabloda yalnızca her iş türü arasında farklılık gösteren kısıtlamalar karşılaştırılmaktadır. Tüm kısıtlamalar için JobScheduler geliştirici sayfası veya iş kısıtlamaları sayfasına bakın.

Aşağıdaki tabloda, belirli bir iş kısıtlamasını destekleyen farklı iş türlerinin yanı sıra WorkManager'ın desteklediği iş kısıtlamaları kümesi gösterilmektedir. Tabloyu bir iş kısıtlama yönteminin adına göre filtrelemek için tablonun önündeki arama çubuğunu kullanın.

Kullanıcı tarafından başlatılan veri aktarım işlerinde izin verilen kısıtlamalar şunlardır:

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

Test

Aşağıdaki listede, uygulamanızın işlerini manuel olarak test etmeye yönelik bazı adımlar gösterilmektedir:

• İş kimliğini almak için, geliştirilmekte olan işin ardından tanımlanan değeri alın.

• Bir işi hemen çalıştırmak veya durdurulan bir işi yeniden denemek için aşağıdaki komutu çalıştırın komutunu girin:

  adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID

• Bir işi zorla durdurması için sistemi simüle etmek (sistem durumu veya (kota dışı koşullar) bir terminal penceresinde aşağıdaki komutu çalıştırın:

  adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID

Ayrıca bkz.

• Arka plan görevlerine genel bakış
• Veri aktarımı arka plan görevi seçenekleri

Ek kaynaklar

Kullanıcı tarafından başlatılan veri aktarımları hakkında daha fazla bilgi için aşağıdaki ek kaynaklara bakın:

• UIDT entegrasyonuyla ilgili örnek olay: Google Haritalar, kullanıcı tarafından başlatılan veri aktarımı API'sini kullanarak indirme güvenilirliğini% 10 artırdı