Bu sayfa, Cloud Translation API ile çevrilmiştir.

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 işleri, 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.

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:

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() {

    ....

}

Manifest dosyasında RUN_USER_INITIATED_JOBS iznini beyan edin:

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

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, 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();

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

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:

İş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.
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.
İş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, WorkManager'ın ön plan hizmeti uygulamasını yedek yaklaşım olarak 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

Hem kullanıcı hem de sistem, kullanıcı tarafından başlatılan aktarım işlerini durdurabilir.

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

Kullanıcı, Görev Yöneticisi'nde görünen kullanıcı tarafından başlatılan bir veri aktarımı işini durdurabilir.

Kullanıcı Durdur'a bastığında sistem aşağıdakileri yapar:

Çalışan diğer tüm işler veya ön plan hizmetleri dahil olmak üzere uygulamanızın işlemini anında sonlandırır.
Çalışan işler için onStopJob() çağrılmaz.
Kullanıcı tarafından görülebilen işlerin yeniden planlanmasını engeller.

Bu nedenle, işin sorunsuz bir şekilde durdurulmasına ve yeniden planlanmasına olanak tanımak için iş için yayınlanan bildirimde kontroller sağlamanız önerilir.

Özel durumlarda Görev Yöneticisi'nde işin yanında Durdur düğmesinin görünmediğini veya işin Görev Yöneticisi'nde hiç gösterilmediğini unutmayın.

Sistem tarafından

Kullanıcı tarafından başlatılan veri aktarımı işleri, normal işlerin aksine uygulama bekleme modu grupları kotalarından etkilenmez. Ancak aşağıdaki koşullardan herhangi biri gerçekleşirse sistem işi durdurur:

Geliştirici tarafından tanımlanan bir kısıtlama artık karşılanmıyor.
Sistem, işin veri aktarımı görevini tamamlamak için gerekenden daha uzun süre çalıştığını belirler.
Sistemin, sistem sağlığına öncelik vermesi ve artan termal durum nedeniyle işleri durdurması gerekir.
Cihaz belleği azaldığı için uygulama işlemi sonlandırıldı.

İş, cihaz belleğinin az olması dışındaki nedenlerle sistem tarafından durdurulduğunda sistem onStopJob() işlevini çağırır ve işi sistemin en uygun zaman olarak belirlediği bir zamanda yeniden dener. Uygulamanızın, onStopJob() çağrılmasa bile veri aktarımı durumunu koruyabildiğinden ve onStartJob() tekrar çağrıldığında bu durumu geri yükleyebildiğinden emin olun.

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

只有当应用处于可见窗口中或满足特定条件时，应用才能启动用户发起的数据传输作业：

如果应用可以从后台启动 activity，则也可以从后台启动用户发起的数据传输作业。
如果应用在最近用过屏幕上现有任务的返回堆栈中有 activity，单靠这一点并不允许运行用户发起的数据传输作业。

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

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

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

注意：下表仅比较了因作业类型而异的约束条件。如需了解所有约束条件，请参阅 JobScheduler 开发者页面或工作约束条件。

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

以下是用户发起的数据传输作业允许使用的约束条件：

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

Test

下面列出了有关如何手动测试应用作业的一些步骤：

如需获取作业 ID，请获取在构建作业时定义的值。
如需立即运行作业或重试已停止的作业，请在终端窗口中运行以下命令：
```
adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID
```
如需模拟系统强行停止作业（由于系统运行状况或超出配额条件），请在终端窗口中运行以下命令：
```
adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID
```

Ayrıca bkz.

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ı

Kullanıcı tarafından başlatılan veri aktarımı Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

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

Kotlin

Java

Kotlin

Java

Kotlin

Java

Öneriler

Geriye dönük uyumluluk

Kotlin

Java

UIDT işlerini durdurma

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

Sistem tarafından

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

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

Test

Ayrıca bkz.

Ek kaynaklar

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