หากต้องการโอนข้อมูลที่อาจใช้เวลานาน คุณสามารถสร้างงาน JobScheduler และระบุว่าเป็นงานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ (UIDT) งาน UIDT มีไว้สำหรับการโอนข้อมูลระยะยาว ซึ่งเริ่มต้นโดยผู้ใช้อุปกรณ์ เช่น การดาวน์โหลดไฟล์จากเซิร์ฟเวอร์ระยะไกล งาน UIDT เปิดตัวพร้อม Android 14 (API ระดับ 34)
งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้จะเริ่มโดยผู้ใช้ งานเหล่านี้ต้องมีการแจ้งเตือน เริ่มต้นทันที และอาจทำงานได้เป็นระยะเวลานานตามที่เงื่อนไขของระบบอนุญาต คุณเรียกใช้งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้หลายงานพร้อมกันได้
ต้องกำหนดเวลางานที่ผู้ใช้เริ่มในขณะที่แอปพลิเคชันแสดงต่อผู้ใช้ (หรือในเงื่อนไขที่อนุญาตอย่างใดอย่างหนึ่ง) หลังจากเป็นไปตามข้อจำกัดทั้งหมดแล้ว ระบบปฏิบัติการจะเรียกใช้การทำงานที่ผู้ใช้เริ่มได้ โดยขึ้นอยู่กับข้อจำกัดด้าน สถานะของระบบ นอกจากนี้ ระบบยังอาจใช้ขนาดเพย์โหลดโดยประมาณที่ระบุเพื่อ พิจารณาระยะเวลาที่งานจะดำเนินการ
ตั้งเวลางานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้
หากต้องการเรียกใช้งานการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ ให้ทำดังนี้
ตรวจสอบว่าแอปได้ประกาศ
JobServiceและสิทธิ์ที่เกี่ยวข้องในไฟล์ Manifest<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<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) // ... .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();
ขณะที่งานกำลังดำเนินการ ให้เรียกใช้
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()เช่น คุณทำได้โดยใช้โครูทีน หากคุณไม่เรียกใช้ Task แบบไม่พร้อมกัน งานจะทำงานในเทรดหลักและอาจบล็อกเทรดหลัก ซึ่งอาจทำให้เกิด ANRหากต้องการหลีกเลี่ยงการเรียกใช้งานนานกว่าที่จำเป็น ให้เรียกใช้
jobFinished()เมื่อการโอนเสร็จสิ้น ไม่ว่าจะสำเร็จหรือล้มเหลว วิธีนี้จะช่วยให้งานไม่ต้องทำงานนานเกินความจำเป็น หากต้องการทราบสาเหตุที่งานหยุดทำงาน ให้ใช้เมธอดเรียกกลับonStopJob()และเรียกJobParameters.getStopReason()
ความเข้ากันได้แบบย้อนหลัง
ขณะนี้ยังไม่มีไลบรารี Jetpack ที่รองรับงาน UIDT ด้วยเหตุนี้ เราขอแนะนำให้คุณควบคุมการเปลี่ยนแปลงด้วยโค้ดที่ยืนยันว่าคุณ ใช้ 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()สำหรับงานที่ทำงานอยู่ - ป้องกันไม่ให้กำหนดเวลางานซึ่งผู้ใช้มองเห็นใหม่
ด้วยเหตุนี้ เราจึงขอแนะนำให้ระบุการควบคุมในการแจ้งเตือนที่โพสต์สำหรับงานเพื่อให้หยุดงานและกำหนดเวลาใหม่ได้อย่างราบรื่น
โปรดทราบว่าในบางกรณี ปุ่มหยุดจะไม่ปรากฏข้างงานใน Task Manager หรืองานจะไม่แสดงใน Task Manager เลย
โดยระบบ
与常规作业不同，用户发起的数据传输作业不受应用待机模式存储分区配额的影响。但是，如果出现以下任一情况，系统仍会停止作业：
- 不再满足开发者定义的约束条件。
- 系统确定该作业的运行时间超出了完成数据传输任务所需的时间。
- 系统需要优先考虑系统运行状况，并因发热程度上升而停止作业。
- 应用进程因设备内存不足而被终止。
如果系统因设备内存不足以外的原因停止作业，系统会调用 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()
การทดสอบ
รายการต่อไปนี้แสดงขั้นตอนการทดสอบงานของแอปด้วยตนเอง
- หากต้องการรับรหัสงาน ให้รับค่าที่กำหนดไว้ในงานที่กำลังสร้าง
หากต้องการเรียกใช้งานทันที หรือหากต้องการลองงานที่หยุดไปแล้วอีกครั้ง ให้เรียกใช้คำสั่งต่อไปนี้ ในหน้าต่างเทอร์มินัล:
adb shell cmd jobscheduler run -f APP_PACKAGE_NAME JOB_ID
เพื่อจำลองการบังคับให้ระบบหยุดงาน (เนื่องจากการทำงานของระบบหรือ เงื่อนไขนอกโควต้า) ให้เรียกใช้คำสั่งต่อไปนี้ในหน้าต่างเทอร์มินัล
adb shell cmd jobscheduler timeout TEST_APP_PACKAGE TEST_JOB_ID
ดูเพิ่มเติม
แหล่งข้อมูลเพิ่มเติม
ดูข้อมูลเพิ่มเติมเกี่ยวกับการโอนข้อมูลที่เริ่มต้นโดยผู้ใช้ได้จากแหล่งข้อมูลเพิ่มเติมต่อไปนี้
- กรณีศึกษาเกี่ยวกับการผสานรวม UIDT: Google Maps ปรับปรุงความน่าเชื่อถือในการดาวน์โหลดได้ 10% โดยใช้ User Initiated Data Transfer API