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>

setUserInitiated() メソッドを JobInfo オブジェクトを作成するときに呼び出します（このメソッドは 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();

ジョブの実行中に、 setNotification() を JobService オブジェクトで呼び出します。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 ジョブを停止する

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

ユーザーがタスクマネージャーから停止

用户可以停止显示在任务管理器中的用户发起的传输作业。

在用户按 Stop 时，系统会执行以下操作：

立即终止应用的进程，包括正在运行的所有其他作业或前台服务。
不针对任何正在运行的作业调用 onStopJob()。
阻止重新调度用户可见的作业。

因此，建议在发布的作业通知中提供控件，以便顺利停止和重新调度作业。

请注意，在特殊情况下，Stop 按钮不会显示在任务管理器中的作业旁边，或者该作业根本不会显示在任务管理器中。

システムによる停止

通常のジョブとは異なり、ユーザーが開始するデータ転送ジョブはアプリスタンバイバケットの割り当ての影響を受けません。ただし、次のいずれかの条件が発生すると、システムはジョブを停止します。

デベロッパー定義の制約が満たされなくなった。
システムにより、ジョブがデータ転送タスクを完了するために必要な時間よりも長く実行されていると判断された。
温度が上昇しているため、システムの健全性を優先してジョブを停止する必要がある。
デバイスのメモリが少ないため、アプリプロセスが強制終了された。

デバイスのメモリ不足以外の理由でシステムによってジョブが停止される場合、システムは onStopJob() を呼び出し、システムが最適だと判断したタイミングでジョブを再試行します。onStopJob() が呼び出されていなくてもアプリがデータ転送状態を保持できることと、onStartJob() が再度呼び出されたときにアプリがこの状態を復元できることを確認してください。

ユーザーが開始するデータ転送ジョブのスケジュールを設定できる条件

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

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

如果作业安排在未满足必要条件的时间运行，则作业将失败并返回 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% 向上させました

ユーザーが開始するデータ転送 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ユーザーが開始するデータ転送ジョブのスケジュールを設定する

Kotlin

Java

Kotlin

Java

Kotlin

Java

推奨事項

下位互換性

Kotlin

Java

UIDT ジョブを停止する

ユーザーがタスク マネージャーから停止

システムによる停止

ユーザーが開始するデータ転送ジョブのスケジュールを設定できる条件

ユーザーが開始するデータ転送ジョブで許可される制約

テスト

関連ドキュメント

参考情報

ユーザーが開始するデータ転送

ユーザーがタスクマネージャーから停止