このページは Cloud Translation API によって翻訳されました。

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

如果您需要执行可能需要很长时间的数据传输，可以创建 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() が再度呼び出されたときにアプリがこの状態を復元できることを確認してください。

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

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

如果应用可以从后台启动 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 ジョブを停止する

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

システムによる停止

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

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

テスト

関連ドキュメント

参考情報

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

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