Документация для разработчиков

AddAgent

mixed
CAgent::AddAgent(
 string name, 
 string module = "", 
 string period = "N", 
 int interval = 86400, 
 string datecheck = "", 
 string active = "Y",
 string next_exec = "", 
 int sort = 100
)

Метод регистрирует новую функцию-агент. Статический метод.

Параметры

ПараметрОписание С версии
name Строка PHP для запуска агента-функции.
module Идентификатор модуля. Необходим для подключения файлов модуля.
Необязательный. По умолчанию пустой.
period

Если значение - "Y", то очередная дата запуска агента (next_exec) будет рассчитываться как:

next_exec = next_exec + interval
Т.е. при очередном запуске, если прошло уже больше времени чем указано в параметре interval, агент сначала будет запускаться ровно столько раз сколько он должен был запуститься (т.е. столько раз сколько он "пропустил"), а затем, когда next_exec достигнет либо превысит текущую дату, он будет в дальнейшем запускаться с периодичностью указанной в параметре interval. Как правило, подобное используется в агентах которые должны гарантированно запуститься определённое количество раз.

Значение period = "Y" соответствует настройке агента в административной панели Периодичность выполнения: точно в указанное время.

Если значение - "N", то очередная дата запуска агента (next_exec) будет рассчитываться как:

next_exec = дата последнего запуска + interval
Т.е. агент после первого запуска будет в дальнейшем запускаться с периодичностью указанной в параметре interval.

Значение period = "N" соответствует настройке агента в административной панели Периодичность выполнения: через заданный интервал.

Параметр необязательный, по умолчанию - "N".
interval Интервал (в секундах), с какой периодичностью запускать агента.
Необязательный. По умолчанию - 86400 (1 сутки).
datecheck Дата первой проверки "не пора ли запустить агент" в формате текущего языка.
Необязательный. По умолчанию - текущее время.
active Активность агента (Y|N).
Необязательный. По умолчанию - "Y" (активен).
next_exec Дата первого запуска агента в формате текущего языка.
Необязательный. По умолчанию - текущее время.
3.1.4
sort Индекс сортировки позволяющий указать порядок запуска данного агента относительно других агентов для которых подошло время запуска.
Необязательный. По умолчанию - 100.
3.2.9

Возвращаемые значения

При успешном выполнении, возвращает ID вновь добавленного агента, иначе - false. Если агент ничего не возвращает, он удаляется. Как правило он должен вернуть вызов самого себя.

См. также

Примеры использования

<?
// добавим агент модуля "Статистика"
CAgent::AddAgent(
    "CStatistic::CleanUpStatistics_2();", // имя функции
    "statistic",                          // идентификатор модуля
    "N",                                  // агент не критичен к кол-ву запусков
    86400,                                // интервал запуска - 1 сутки
    "07.04.2005 20:03:26",                // дата первой проверки на запуск
    "Y",                                  // агент активен
    "07.04.2005 20:03:26",                // дата первого запуска
    30);
?>
<?
// добавим агент модуля "Техподдержка"
CAgent::AddAgent(
    "CTicket::AutoClose();",  // имя функции
    "support",                // идентификатор модуля
    "N",                      // агент не критичен к кол-ву запусков
    86400,                    // интервал запуска - 1 сутки
    "",                       // дата первой проверки - текущее
    "Y",                      // агент активен
    "",                       // дата первого запуска - текущее
    30);
?>
<?
// добавим произвольный агент не принадлежащий ни одному модулю
CAgent::AddAgent("My_Agent_Function();");
?>

<?
// файл /bitrix/php_interface/init.php

function My_Agent_Function()
{
   // выполняем какие-либо действия
   return "My_Agent_Function();";
}
?>
<?
// добавим произвольный агент принадлежащий модулю
// с идентификатором my_module

CAgent::AddAgent(
   "CMyModule::Agent007(1)", 
   "my_module", 
   "Y", 
    86400);
?>

<?
// данный агент будет запущен ровно 7 раз с периодичностью раз в сутки, 
// после чего будет удален из таблицы агентов.

Class CMyModule
{
   function Agent007($cnt=1)
   {
      echo "Hello!";
      if($cnt>=7)
         return "";
      return "CMyModule::Agent007(".($cnt+1).")";
   }
}
?>


Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
0
Роман Зебров
Сообщение непромодерировано, возможны ошибки и неточности.
Цитата
Владислав Морсин пишет:
то тогда в конце выполнения функции агента удаляйте текущего агента и создавайте нового.
Можно так-же указать интервал выполнения на пару секунд меньше нужного, в вашем примере указать не 600 секунд, а например 570. Так как крон запускается раз в минуту функция проверки будет считать что агент должен был выполниться несколько секунд назад и запустит его,  дату следующего выполнения поставит через 570 секунд, а это не кратно одной минуте и в момент следующей проверки ситуация повторится. На сколько меньше ставить время надо опытным путем для каждой отдельной задачи выявлять.
Было проверено на боевом сайте, агент запускался раз в день. Когда был указан ровный интервал (86400) то с каждым срабатыванием происходило смещение следующего запуска на 1 минуту. После того как изменили интервал на 86370 смещение прекратилось.
0
Владислав Морсин
Сообщение непромодерировано, возможны ошибки и неточности.
Цитата
next_exec = дата последнего запуска + interval
На самом деле под датой последнего запуска тут подразумевается дата окончания работы агента (NOW), а вовсе не дата начала его работы.

Цитата
Т.е. агент после первого запуска будет в дальнейшем запускаться с периодичностью указанной в параметре interval.  
И тут тоже неточная информация, он будет запускаться с периодичностью interval + время очередного выполнения.
Т.е. если дата следующего запуска установлена как "24.01.2020 18:00:00", а периодичность 600 секунд, то когда агент начнет выполняться, допустим, в 18:00:01, и будет выполняться 10 секунд, то в следующий раз он будет выполнен не раньше, чем в 18:10:11. При этом, если агенты вынесены на cron, который запускается раз в минуту, то в очередь он попадет, когда задача cron запустится в 18:11:00.
Если нужно, чтобы непериодический агент выполнялся именно с определенной частотой без отклонений в минуту-другую, то тогда в конце выполнения функции агента удаляйте текущего агента и создавайте нового.
0
Иван Левый
Если нужно получить в агенте дату, для которого он запущен, можно в функции агента найти дату его следующего запуска.

Например:
Код
CAgent::AddAgent(
    "CTimeSystem::UpdateStatistic();",     // имя функции
    "timesystem",                         // идентификатор модуля
    "Y",                                  // агент критичен к кол-ву запусков
    86400,                          // интервал запуска
   "",                             // когда проверить первый запуск? (сейчас)
   "Y",                          // агент активен
   date("01.03.2009")                 // начиная с какой даты проверять?
);


Допустим, сегодня 17-ое марта. Агент должен запуститься ровно 17 раз, так как с 1-го марта прошло 17 дней.

Чтобы получить в агенте дату, для которой он каждый раз срабатывал, можно делать так:
Код
   function UpdateStatistic()
   {
      $curr_date = "";
      // Находим дату, для которой запущен данный агент
      $arFilter = array(
         "NAME" => "CTimeSystem::UpdateStatistic();",
         );
      $curr_agent = CAgent::GetList(array(), $arFilter);
      if ($curr_agent = $curr_agent->GetNext())
         $curr_date = ConvertTimeStamp(MakeTimeStamp($curr_agent["NEXT_EXEC"]), "SHORT"); 


      // Добавляем смены на сегодня
      CTimeSystemBusiness::FillSmenaTime($curr_date);      

      // Обновляем статистику за вчера 
      CTimeSystemBusiness::AddToStatByDay( ConvertTimeStamp($curr_date - 86400) );

      // AddMessage2Log("Занятость механиков за ".ConvertTimeStamp(time() - 86400)." обновлена.", "timesystem");   
      
      return 'CTimeSystem::UpdateStatistic();';
   }


Еще один вариант - передавать параметр в агенте
Код
CTimeSystem::UpdateStatistic('01.03.2009'); 


и в return подставлять следующий день
Код
return 'CTimeSystem::UpdateStatistic('02.03.2009');'; 
© «Битрикс», 2001-2020, «1С-Битрикс», 2020
Наверх