Планировщик заданий AndroidAndroid Job Scheduler

В этом руководстве описывается планирование фоновой работы, с помощью Android API планировщика заданий, которое доступно на устройствах Android под управлением Android 5.0 (уровень API 21) и более поздних версий.This guide discusses how to schedule background work using the Android Job Scheduler API, which is available on Android devices running Android 5.0 (API level 21) and higher.

ОбзорOverview

Один из лучших способов сохранения приложение Android в других — убедитесь, что сложных или длительных работа выполняется в фоновом режиме.One of the best ways to keep an Android application responsive to the user is to ensure that complex or long running work is performed in the background. Тем не менее очень важно, что фоновая работа не скажется негативно на удобство работы пользователя с устройством.However, it is important that background work will not negatively impact the user's experience with the device.

Например фоновое задание может выполнять опрос веб-сайта каждые три или четыре минуты запроса для изменения для конкретного набора данных.For example, a background job might poll a website every three or four minutes to query for changes to a particular dataset. Это кажется истинно, однако он будет иметь катастрофические последствия на батареи.This seems benign, however it would have a disastrous impact on battery life. Приложение несколько раз будет пробуждения устройства, повышать ЦП до более высокого состояния питания, питание радио, сетевые запросы, а затем обработки результатов.The application will repeatedly wake up the device, elevate the CPU to a higher power state, power up the radios, make the network requests, and then processing the results. Она становится еще серьезнее, так как устройство не сразу выключить питание и будут возвращены в состояние бездействия низкого энергопотребления.It gets worse because the device will not immediately power down and return to the low-power idle state. Плохо запланированных фоновой работы могут случайно сохранить устройства в состоянии требованиям ненужное и излишнее power.Poorly scheduled background work may inadvertently keep the device in a state with unnecessary and excessive power requirements. Этот внешне безобидный действия (веб-сайт опроса) сделает устройства недоступными в относительно короткий период времени.This seemingly innocent activity (polling a website) will render the device unusable in a relatively short period of time.

Android предоставляет следующие интерфейсы API для выполнения работы в фоновом режиме, но сами по себе они не являются достаточными для планирования intelligent заданий.Android provides the following APIs to help with performing work in the background but by themselves they are not sufficient for intelligent job scheduling.

  • Службы Intent – цель службы отлично подходят для выполнения работы, однако они не предоставляют способа для планирования работы.Intent Services – Intent Services are great for performing the work, however they provide no way to schedule work.
  • AlarmManager – эти программные интерфейсы приложения позволяют только работу, чтобы запланировать, но не позволяют для фактического выполнения работы.AlarmManager – These APIs only allow work to be scheduled but provide no way to actually perform the work. Кроме того AlarmManager разрешает только ограничения на основе времени, это означает, что создано оповещение в определенное время или после истечения определенного периода времени.Also, the AlarmManager only allows time based constraints, which means raise an alarm at a certain time or after a certain period of time has elapsed.
  • Широковещательные приемники – приложение Android, можно настроить широковещательных получателей для выполнения работы в ответ на события уровня системы или намерения.Broadcast Receivers – An Android app can setup broadcast receivers to perform work in response to system-wide events or Intents. Тем не менее широковещательных получателей не предоставляют контролировать выполнения задания.However, broadcast receivers don't provide any control over when the job should be run. Также будет ограничить изменения в ОС Android при широковещательных получателей, или работать виды работ, который можно ответить.Also changes in the Android operating system will restrict when broadcast receivers will work, or the kinds of work that they can respond to.

Существуют два ключевых компонента для эффективного выполнения фоновой работы (иногда называется фоновое задание или задания):There are two key features to efficiently performing background work (sometimes referred to as a background job or a job):

  1. Интеллектуально планирования работы – очень важно, что когда приложение выполняет работу в фоновом режиме, она делает это как соблюсти корректность.Intelligently scheduling the work – It is important that when an application is doing work in the background that it does so as a good citizen. В идеальном случае приложения не должен требовать выполнение задания.Ideally, the application should not demand that a job be run. Вместо этого приложение должно указать условия, которые должны быть выполнены для, когда задание можно запускать и запланировать выполнение задания с операционной системой, которое будет выполнять работу, при соблюдении условий.Instead, the application should specify conditions that must be met for when the job can run, and then schedule that job with the operating system that will perform the work when the conditions are met. Это позволяет Android для запуска задания для обеспечения максимальной эффективности на устройстве.This allows Android to run the job to ensure maximum efficiency on the device. Например сетевых запросов может быть в пакетном режиме для запуска всех в то же время, чтобы обеспечивает максимальное использование издержки, связанные с сетью.For example, network requests may be batched to run all at the same time to make maximum use of overhead involved with networking.
  2. Инкапсуляция работы – код для выполнения фоновой работы должна быть включена в отдельный компонент, могут выполняться независимо от пользовательского интерфейса и будет сравнительно легко изменить расписание, если не удается завершить работу по некоторым причинам.Encapsulating the work – The code to perform the background work should be encapsulated in a discrete component that can be run independently of the user interface and will be relatively easy to reschedule if the work fails to complete for some reason.

Планировщик заданий Android — это платформа, встроенная в ОС Android, предоставляющий fluent API для упрощения планирования фоновой работы.The Android Job Scheduler is a framework built in to the Android operating system that provides a fluent API to simplify scheduling background work. Планировщик заданий Android состоит из следующих типов:The Android Job Scheduler consists of the following types:

  • Android.App.Job.JobScheduler — Это системная служба, которая используется для планирования, выполнения и при необходимости отменить, задания от имени приложения Android.The Android.App.Job.JobScheduler is a system service that is used to schedule, execute, and if necessary cancel, jobs on behalf of an Android application.
  • Android.App.Job.JobService — Это абстрактный класс, который необходимо расширить с помощью логики, который будет выполняться задание в основном потоке приложения.An Android.App.Job.JobService is an abstract class that must be extended with the logic that will run the job on the main thread of the application. Это означает, что JobService отвечает за как работа будет выполняться асинхронно.This means that the JobService is responsible for how the work is to be performed asynchronously.
  • Android.App.Job.JobInfo Объект содержит условия, которым руководство по Android, если задание должно запускаться.An Android.App.Job.JobInfo object holds the criteria to guide Android when the job should run.

Для планирования работы с Android планировщик заданий, приложения Xamarin.Android необходимо инкапсулировать код в класс, расширяющий JobService класса.To schedule work with the Android Job Scheduler, a Xamarin.Android application must encapsulate the code in a class that extends the JobService class. JobService поддерживает три метода жизненного цикла, которые могут вызываться в течение времени существования задания.JobService has three lifecycle methods that can be called during the lifetime of the job:

  • bool (JobParameters параметров) OnStartJob – этот метод вызывается JobScheduler для выполнения работы и выполняется в основном потоке приложения.bool OnStartJob(JobParameters parameters) – This method is called by the JobScheduler to perform work, and runs on the main thread of the application. Он отвечает за JobService для выполнения работы в асинхронном режиме и true остающуюся, если работу или false Если работу.It is the responsibility of the JobService to asynchronously perform the work and true if there is work remaining, or false if the work is done.

    Когда JobScheduler вызывает этот метод, он будет запрашивать и сохранять wakelock из Android в течение всего задания.When the JobScheduler calls this method, it will request and retain a wakelock from Android for the duration of the job. После завершения задания он отвечает за JobService сообщить JobScheduler этого факта вызовом JobFinished (описывается далее).When the job is finished, it is the responsibility of the JobService to tell the JobScheduler of this fact by call the JobFinished method (described next).

  • JobFinished (параметры JobParameters, bool needsReschedule) – этот метод должен вызываться JobService сообщить JobScheduler , работу.JobFinished(JobParameters parameters, bool needsReschedule) – This method must be called by the JobService to tell the JobScheduler that the work is done. Если JobFinished не вызывается, JobScheduler не удалит wakelock, приводит к разряду батареи ненужные.If JobFinished is not called, the JobScheduler will not remove the wakelock, causing unnecessary battery drain.

  • bool (JobParameters параметров) OnStopJob – вызывается, когда задание останавливается преждевременно системой Android.bool OnStopJob(JobParameters parameters) – This is called when the job is prematurely stopped by Android. Он должен вернуть true Если задание должно быть перепланировано на основе критериев повторных попыток (ниже более подробно рассматривается).It should return true if the job should be rescheduled based on the retry criteria (discussed below in more detail).

Можно указать ограничения или триггеры , будет контролировать, когда задание можно или следует запустить.It is possible to specify constraints or triggers that will control when a job can or should run. Например можно ограничить задание будет выполняться только при зарядки устройства или для запуска задания, если изображение извлекается.For example, it is possible to constrain a job so that it will only run when the device is charging or to start a job when a picture is taken.

В этом руководстве подробно расскажет способы реализации JobService класса и запланировать его с JobScheduler.This guide will discuss in detail how to implement a JobService class and schedule it with the JobScheduler.

ТребованияRequirements

Планировщик заданий Android требуется Android API уровня 21 (Android 5.0) или более поздней версии.The Android Job Scheduler requires Android API level 21 (Android 5.0) or higher.

С помощью планировщика заданий AndroidUsing the Android Job Scheduler

С помощью Android JobScheduler API трех этапов:There are three steps for using the Android JobScheduler API:

  1. Реализуйте JobService тип для инкапсуляции работы.Implement a JobService type to encapsulate the work.
  2. Используйте JobInfo.Builder создаваемого объекта JobInfo , содержащий критерии для JobScheduler для запуска задания.Use a JobInfo.Builder object to create the JobInfo object that will hold the criteria for the JobScheduler to run the job.
  3. Запланировать задание с помощью JobScheduler.Schedule.Schedule the job using JobScheduler.Schedule.

Реализуйте JobServiceImplement a JobService

Вся работа, выполняемых библиотекой Android планировщик заданий, которые должны выполняться в тип, который расширяет Android.App.Job.JobService абстрактного класса.All work performed by the Android Job Scheduler library must be done in a type that extends the Android.App.Job.JobService abstract class. Создание JobService очень похоже на создание Service с помощью платформы Android:Creating a JobService is very similar to creating a Service with the Android framework:

  1. Расширить JobService класса.Extend the JobService class.
  2. Украшение подкласс с ServiceAttribute и задайте Name параметр в строку, состоящую из имени пакета и имя класса (см. ниже).Decorate the subclass with the ServiceAttribute and set the Name parameter to a string that is made up of the package name and the name of the class (see the following example).
  3. Задайте Permission свойство ServiceAttribute к строке android.permission.BIND_JOB_SERVICE.Set the Permission property on the ServiceAttribute to the string android.permission.BIND_JOB_SERVICE.
  4. Переопределить OnStartJob метод, добавив код для выполнения работы.Override the OnStartJob method, adding the code to perform the work. Android будет вызывать этот метод в основном потоке приложения для запуска задания.Android will invoke this method on the main thread of the application to run the job. Трудозатраты займет больше времени, что несколько миллисекунд должна выполняться в потоке, чтобы избежать блокировки приложения.Work that will take longer that a few milliseconds should be performed on a thread to avoid blocking the application.
  5. По завершении работы JobService необходимо вызвать JobFinished метод.When the work is done, the JobService must call the JobFinished method. Этот метод является как JobService сообщает JobScheduler выполняется работа.This method is how JobService tells the JobScheduler that work is done. Сбой при вызове JobFinished приведет к JobService помещения ненужные требования на устройстве, Сокращение срока службы аккумулятора.Failure to call JobFinished will result in the JobService putting unnecessary demands on the device, shortening the battery life.
  6. Рекомендуется также переопределить OnStopJob метод.It is a good idea to also override the OnStopJob method. Этот метод вызывается системой Android, когда задание завершает работу, прежде чем его завершит и предоставляет JobService возможность правильно ликвидируйте все ресурсы.This method is called by Android when the job is being shut down before it is finished and provides the JobService with an opportunity to properly dispose of any resources. Этот метод должен возвращать true при необходимости изменить расписание задания, или false если он не является желательным, чтобы повторно запустить задание.This method should return true if it is necessary to reschedule the job, or false if it is not desireable to re-run the job.

Ниже приведен пример простой JobService для приложения, используя TPL для асинхронного выполнения определенных действий:The following code is an example of the simplest JobService for an application, using the TPL to asynchronously perform some work:

[Service(Name = "com.xamarin.samples.downloadscheduler.DownloadJob", 
         Permission = "android.permission.BIND_JOB_SERVICE")]
public class DownloadJob : JobService
{
    public override bool OnStartJob(JobParameters jobParams)
    {            
        Task.Run(() =>
        {
            // Work is happening asynchronously
                      
            // Have to tell the JobScheduler the work is done. 
            JobFinished(jobParams, false);
        });

        // Return true because of the asynchronous work
        return true;  
    }

    public override bool OnStopJob(JobParameters jobParams)
    {
        // we don't want to reschedule the job if it is stopped or cancelled.
        return false; 
    }
}

Создание JobInfo планирование выполнения заданийCreating a JobInfo to schedule a job

Не следует создавать экземпляры приложений Xamarin.Android JobService напрямую, вместо этого они будут передавать JobInfo объект JobScheduler.Xamarin.Android applications do not instantiate a JobService directly, instead they will pass a JobInfo object to the JobScheduler. JobScheduler Будет создавать экземпляр запрошенного JobService объекта, планирования и запуска JobService в соответствии с метаданными JobInfo.The JobScheduler will instantiate the requested JobService object, scheduling and running the JobService according to the metadata in the JobInfo. Объект JobInfo объект должен содержать следующие сведения:A JobInfo object must contain the following information:

  • JobId – это int значение, используемое для идентификации задания JobScheduler.JobId – this is an int value that is used to identify a job to the JobScheduler. Повторное использование этого значения будет обновлять все существующие задания.Reusing this value will update any existing jobs. Значение должно быть уникальным для приложения.The value must be unique for the application.
  • JobService – этот параметр является ComponentName , явным образом определяющий тип, JobScheduler следует использовать для выполнения задания.JobService – this parameter is a ComponentName that explicitly identifies the type that the JobScheduler should use to run a job.

Этот метод расширения демонстрирует создание JobInfo.Builder с Android Context, например, действия:This extension method demonstrates how to create a JobInfo.Builder with an Android Context, such as an Activity:

public static class JobSchedulerHelpers
{
    public static JobInfo.Builder CreateJobBuilderUsingJobId<T>(this Context context, int jobId) where T:JobService
    {
        var javaClass = Java.Lang.Class.FromType(typeof(T));
        var componentName = new ComponentName(context, javaClass);
        return new JobInfo.Builder(jobId, componentName);
    }
}

// Sample usage - creates a JobBuilder for a DownloadJob and sets the Job ID to 1.
var jobBuilder = this.CreateJobBuilderUsingJobId<DownloadJob>(1);

var jobInfo = jobBuilder.Build();  // creates a JobInfo object.

Это мощная функция Android планировщик заданий является возможность контролировать, когда выполняется задание или условий задания могут выполняться.A powerful feature of the Android Job Scheduler is the ability to control when a job runs or under what conditions a job may run. В следующей таблице описаны некоторые из методов на JobInfo.Builder , которые позволяют приложению влияют на время выполнения заданий:The following table describes some of the methods on JobInfo.Builder that allow an app to influence when a job can run:

МетодMethod ОписаниеDescription
SetMinimumLatency Выполнение задержки (в миллисекундах), необходимо соблюдать перед заданием.Specifies that a delay (in milliseconds) that should be observed before a job is run.
SetOverridingDeadline Объявляет, что задание необходимо выполнить до истечения этого времени (в миллисекундах).Declares the that the job must run before this time (in milliseconds) has elapsed.
SetRequiredNetworkType Указывает требования к сети для задания.Specifies the network requirements for a job.
SetRequiresBatteryNotLow Задание может выполняться только в том случае, когда устройство не отображает предупреждение «низкого заряда батарей» для пользователя.The job may only run when the device is not displaying a "low battery" warning to the user.
SetRequiresCharging Задание может выполняться только в том случае, когда зарядки.The job may only run when the battery is charging.
SetDeviceIdle Задание выполняется в том случае, если устройство занято.The job will run when the device is busy.
SetPeriodic Указывает, что задание должно выполняться регулярно.Specifies that the job should be regularly run.
SetPersisted Задание должно perisist сохранялся при перезагрузке устройства.The job should perisist across device reboots.

SetBackoffCriteria Даны некоторые рекомендации о том, как долго JobScheduler ожидания перед попыткой снова выполнить задание.The SetBackoffCriteria provides some guidance on how long the JobScheduler should wait before trying to run a job again. Критерии отсрочки, состоит из двух частей: задержки в миллисекундах (значение по умолчанию 30 секунд) и тип отхода, которая должна использоваться (иногда называется политики отсрочки или политика повтора) .There are two parts to the backoff criteria: a delay in milliseconds (default value of 30 seconds)and type of back off that should be used (sometimes referred to as the backoff policy or the retry policy). Две политики, инкапсулируются в Android.App.Job.BackoffPolicy перечисления:The two policies are encapsulated in the Android.App.Job.BackoffPolicy enum:

  • BackoffPolicy.Exponential – Политику экспоненциального откладывания будет увеличиваться экспоненциально значение начальной задержки после каждой ошибки.BackoffPolicy.Exponential – An exponential backoff policy will increase the initial backoff value exponentially after each failure. При первом сбое задания библиотеки будет ожидать начальный интервал, который указывается перед Перепланирование задания — пример 30 секунд.The first time a job fails, the library will wait the initial interval that is specified before rescheduling the job – example 30 seconds. Во второй раз в случае сбоя задания библиотеки будет ожидать по крайней мере 60 секунд, прежде чем пытаться запустить задание.The second time the job fails, the library will wait at least 60 seconds before trying to run the job. После третьей неудачной попытки, библиотека ожидания 120 секунд и т. д.After the third failed attempt, the library will wait 120 seconds, and so on. Это значение по умолчанию.This is the default value.
  • BackoffPolicy.Linear – Эта стратегия является линейной задержки задания должен быть запланирован повторно для выполнения через заданные интервалы времени (до ее успешного выполнения).BackoffPolicy.Linear – This strategy is a linear backoff that the job should be rescheduled to run at set intervals (until it succeeds). Линейный выдержкой лучше всего подходит для работы, которая должна быть выполнена как можно скорее или проблемы, которые быстро устранить самостоятельно.Linear backoff is best suited for work that must be completed as soon as possible or for problems that will quickly resolve themselves.

Дополнительные сведения о создании JobInfo объекта, см. в статье документации Google для JobInfo.Builder класс.For more details on create a JobInfo object, please read Google's documentation for the JobInfo.Builder class.

Передача параметров задания с помощью JobInfoPassing parameters to a job via the JobInfo

Параметры передаются в задание, создав PersistableBundle , передается вместе с Job.Builder.SetExtras метод:Parameters are passed to a job by creating a PersistableBundle that is passed along with the Job.Builder.SetExtras method:

var jobParameters = new PersistableBundle();
jobParameters.PutInt("LoopCount", 11);

var jobBuilder = this.CreateJobBuilderUsingJobId<DownloadJob>(1)
                     .SetExtras(jobParameters)
                     .Build();

PersistableBundle Осуществляется из Android.App.Job.JobParameters.Extras свойство в OnStartJob метод JobService:The PersistableBundle is accessed from the Android.App.Job.JobParameters.Extras property in the OnStartJob method of a JobService:

public override bool OnStartJob(JobParameters jobParameters)
{
    var loopCount = jobParams.Extras.GetInt("LoopCount", 10);
    
    // rest of code omitted
} 

Планирование заданияScheduling a job

Чтобы запланировать задание, приложения Xamarin.Android будет получить ссылку на JobScheduler системной службы и вызов JobScheduler.Schedule метод с JobInfo , созданного на предыдущем шаге.To schedule a job, a Xamarin.Android application will get a reference to the JobScheduler system service and call the JobScheduler.Schedule method with the JobInfo object that was created in the previous step. JobScheduler.Schedule немедленно вернет с одним из двух целочисленных значений:JobScheduler.Schedule will immediately return with one of two integer values:

  • JobScheduler.ResultSuccess – успешно запланировано задание.JobScheduler.ResultSuccess – The job has been successfully scheduled.
  • JobScheduler.ResultFailure – не удалось запланировать задание.JobScheduler.ResultFailure – The job could not be scheduled. Обычно это вызвано конфликтующие JobInfo параметров.This is typically caused by conflicting JobInfo parameters.

Этот код является примером планирования задания и уведомления пользователя о результатах попытки планирования:This code is an example of scheduling a job and notifying the user of the results of the scheduling attempt:

var jobScheduler = (JobScheduler)GetSystemService(JobSchedulerService);
var scheduleResult = jobScheduler.Schedule(jobInfo);

if (JobScheduler.ResultSuccess == scheduleResult)
{
    var snackBar = Snackbar.Make(FindViewById(Android.Resource.Id.Content), Resource.String.jobscheduled_success, Snackbar.LengthShort);
    snackBar.Show();
}
else
{
    var snackBar = Snackbar.Make(FindViewById(Android.Resource.Id.Content), Resource.String.jobscheduled_failure, Snackbar.LengthShort);
    snackBar.Show();
}

Отмена заданияCancelling a job

Его невозможно отменить все задания, которые запланированы или просто одного задания с помощью JobsScheduler.CancelAll() метод или JobScheduler.Cancel(jobId) метод:It is possible to cancel all the jobs that have been scheduled, or just a single job using the JobsScheduler.CancelAll() method or the JobScheduler.Cancel(jobId) method:

// Cancel all jobs
jobScheduler.CancelAll(); 

// to cancel a job with jobID = 1
jobScheduler.Cancel(1)

СводкаSummary

В этом руководстве рассматриваются способы использования Android планировщика заданий для интеллектуально выполнения работы в фоновом режиме.This guide discussed how to use the Android Job Scheduler to intelligently perform work in the background. Рассматривался инкапсулировать работа, которую можно выполнить как JobService и способы использования JobScheduler запланировать эту работу, указав критерии, согласно JobTrigger и способ обработки ошибок с RetryStrategy.It discussed how to encapsulate the work to be performed as a JobService and how to use the JobScheduler to schedule that work, specifying the criteria with a JobTrigger and how failures should be handled with a RetryStrategy.