Агенты в 1С-Битрикс запускаются не через cron хостинга, а на хитах посетителей: в самом конце загрузки каждой страницы, уже после того как контент отдан браузеру, система проверяет очередь агентов и запускает те, что подошли по времени. Большинство разработчиков видит агенты только через админку, раздел «Список агентов» в настройках продукта. На практике регистрировать агента удобнее прямо из кода модуля или обработчика события, а для этого нужен метод CAgent::AddAgent. Расскажу, какие параметры этого метода реально важны, как не наплодить дублей при каждой загрузке страницы и когда агента пора переносить на cron.
Что такое агент Битрикс и зачем регистрировать его кодом
Агент, по определению из документации платформы, это технология для запуска произвольных PHP-функций с заданной периодичностью. Ключевое отличие от привычного cron в том, что момент запуска определяется не системными часами сервера, а посещаемостью сайта: агент срабатывает, когда кто-то заходит на страницу и система видит, что подошло время очередного выполнения.
На практике через CAgent::AddAgent я регистрирую задачи вроде:
- ночная очистка временных файлов экспорта или превью изображений старше недели
- дайджест новых заявок для менеджера раз в сутки
- синхронизация курсов валют или остатков с внешним сервисом по расписанию
- деактивация просроченных промокодов и временных скидок в каталоге
- напоминание клиенту о неоплаченном заказе через сутки после оформления
Для интернет-магазина на 1С-Битрикс такой подход особенно удобен там, где логика завязана на внутренние сущности каталога: агент выполняется в контексте ядра платформы, без отдельного скрипта и без прав на crontab у хостинга. Регистрация через код, а не через ручной ввод в админке, даёт ещё один плюс: агент переезжает вместе с проектом на тестовый и боевой сервер как обычный код модуля, а не как настройка, которую легко забыть повторить руками.
CAgent::AddAgent: сигнатура и параметры метода
Чтобы агент выполнился в заданное время, его нужно зарегистрировать методом CAgent::AddAgent. Вызов делают один раз, обычно в методе установки модуля или в php-скрипте, который выполняют вручную через административную консоль.
CAgent::AddAgent(
"cleanup_old_exports();", // имя функции с круглыми скобками и параметрами
"main", // код модуля, который регистрирует агента
"N", // периодичность: N - непериодический агент, Y - периодический
86400, // интервал между запусками в секундах
"", // дата первой проверки агента на запуск
"Y", // активность агента
"", // дата следующего выполнения, пусто - запустится на ближайшем хите
100 // сортировка в списке агентов
);
Первый параметр это не просто имя функции, а готовая строка PHP-кода с круглыми скобками и, при необходимости, аргументами: система выполнит этот код при срабатывании агента. Второй параметр, код модуля, пригодится при поиске агента в общем списке и при удалении регистрации. Интервал задаётся в секундах, а не в минутах или часах, это частая ошибка при копировании кода без проверки: вместо суток в 86400 секунд легко случайно поставить 86400 минут и получить агент, который почти никогда не запускается.
Отдельный момент, который легко упустить, это возвращаемое значение функции-агента. По документации, функция должна вернуть PHP-код, который система использует при следующем запуске. Проще говоря, функция сама заново регистрирует себя на каждом выполнении:
function cleanup_old_exports()
{
$dir = $_SERVER["DOCUMENT_ROOT"] . "/upload/exports/";
foreach (glob($dir . "*.csv") as $file) {
if (filemtime($file) < strtotime("-7 days")) {
unlink($file);
}
}
return "cleanup_old_exports();";
}
Если забыть про return или вернуть пустую строку, после выполнения агент удалится из списка агентов и больше не запустится. Так намеренно делают одноразовые агенты, но для регулярной задачи это тихая поломка. Это одно из мест в связке, где легко получить тихо сломанный агент.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Как зарегистрировать агента без дублей на каждом хите
Если просто вставить вызов CAgent::AddAgent в init.php или в обработчик события, который срабатывает на каждой загрузке страницы, метод будет вызываться на каждом хите. Дубль он сам не создаст: у AddAgent есть параметр «выдавать ошибку при дублировании агента», но лишний запрос к базе и ошибка на каждой странице ни к чему. Перед регистрацией стоит проверить, нет ли уже такого агента, через CAgent::GetList с фильтром по имени функции и коду модуля:
$dbAgentList = CAgent::GetList(
[],
[
"NAME" => "cleanup_old_exports();",
"MODULE_ID" => "main",
]
);
if (!$dbAgentList->Fetch()) {
CAgent::AddAgent(
"cleanup_old_exports();",
"main",
"N",
86400,
"",
"Y",
"",
100
);
}
Ещё надёжнее регистрировать агента не в общем init.php, а разово: в методе установки собственного модуля или через php-консоль в административной панели, а не в коде, который выполняется на каждой странице сайта.
Периодические и непериодические агенты на практике
В документации агенты делятся на два типа. Периодические запускаются в заданное время, а время следующего запуска считается как время предыдущего плюс интервал. У этого подхода есть побочный эффект: если сайт не работал час, а интервал агента 10 минут, при первом же визите после простоя агент выполнится подряд несколько раз, пытаясь наверстать пропущенные запуски.
Непериодические агенты устроены иначе: они запускаются через заданный интервал и только после успешного завершения предыдущего выполнения, что исключает такие накладки. По документации, абсолютное большинство агентов именно непериодические, и в CAgent::AddAgent за это отвечает третий параметр period: значение “N”, как в листинге выше, регистрирует непериодического агента.
Для задач вроде ночной очистки файлов или дайджеста заявок непериодический режим почти всегда предпочтительнее: не будет ситуации, когда после ночного простоя хостинга агент отправит менеджеру пять одинаковых писем подряд за пару секунд.
Где посмотреть зарегистрированных агентов и как их удалить
Список всех агентов, зарегистрированных в системе, открывается в административной панели на странице «Список агентов» (Настройки > Настройки продукта > Агенты). Там видно код модуля, интервал, статус активности и дату следующего запуска, это первое место, куда стоит заглянуть, если задача выполняется не вовремя или не выполняется вовсе.
Удаляется регистрация через CAgent::RemoveAgent, парой к CAgent::AddAgent:
CAgent::RemoveAgent("cleanup_old_exports();", "main");
Важно передавать точно ту же строку имени функции и тот же код модуля, что были при регистрации, иначе метод просто не найдёт нужную запись. На практике я держу имя агента и код модуля в одном месте кода, например в константах, чтобы AddAgent и RemoveAgent со временем не разошлись при правках.
Ограничения агента и перенос выполнения на cron
У кода, который выполняется внутри агента, урезанный контекст по сравнению с обычной страницей сайта. В документации прямо перечислено: переменная USER внутри агента отсутствует, авторизацию через Authorize вызывать нельзя, константа SITE_ID не определена, потому что агент может выполниться и в административном разделе. Плюс агенты выполняются в однопоточном режиме с блокировкой на MySQL на 10 минут: новый вызов агента возможен только после того, как отработал предыдущий, а блокировка защищает от повторного запуска того же агента, на другие агенты она не влияет.
Агентом, которому требуется больше 10 секунд на выполнение, документация прямо называет тяжёлым и рекомендует для таких задач фоновый запуск через cron, а не выполнение на хите. Разница между двумя режимами такая:
| Параметр | Агент на хите (по умолчанию) | Агент на cron |
|---|---|---|
| Что запускает выполнение | Заход посетителя на страницу сайта | Системное расписание crontab на хостинге |
| Точность времени | Зависит от посещаемости, может запаздывать | Точная, привязана к минутам crontab |
| Влияние на посетителя | Замедляет отдачу той страницы, на которой сработал | Не влияет на скорость отдачи страниц |
| Что нужно для настройки | Ничего, работает сразу после AddAgent | Доступ к crontab на хостинге и правка dbconn.php |
Перенос на cron делают в несколько шагов. Сначала через php-консоль в административной панели переключают два системных параметра: COption::SetOptionString("main", "agents_use_crontab", "N"); и COption::SetOptionString("main", "check_agents", "N");. Дальше из файла /bitrix/php_interface/dbconn.php убирают прежние определения констант BX_CRONTAB_SUPPORT и BX_CRONTAB и вместо них прописывают BX_CRONTAB_SUPPORT внутри проверки константы CHK_EVENT, а рядом создают файл /bitrix/php_interface/cron_events.php, через который агенты будут запускаться из системного планировщика. В сам crontab добавляют строку вида */1 * * * * /usr/bin/php -f /home/bitrix/www/bitrix/php_interface/cron_events.php, и с этого момента агенты обрабатываются раз в минуту из-под cron, а не на хитах посетителей.
Если правка dbconn.php и перенос агентов кажутся рискованными для боевого магазина, разумнее доверить это доработке и поддержке 1С-Битрикс с проверкой на тестовом окружении перед выкладкой на прод.
Возможности и поведение агентов в 1С-Битрикс меняются от версии к версии платформы, поэтому перед внедрением в боевой проект я сверяюсь с актуальной документацией вендора.
Частые вопросы
Чем CAgent::AddAgent отличается от обычного cron-задания на хостинге?
Cron-задание запускается системным планировщиком строго по расписанию независимо от того, заходит ли кто-то на сайт. Агент, зарегистрированный через CAgent::AddAgent, по умолчанию выполняется на хите: система проверяет очередь агентов после отдачи очередной страницы посетителю. Время срабатывания зависит от посещаемости сайта, и при низком трафике возможна задержка. Перенос на cron убирает эту зависимость, но требует доступа к crontab и правки dbconn.php.
Что будет, если функция-агент выполняется дольше 10 секунд?
Такой агент документация называет тяжёлым и не рекомендует оставлять на выполнение через хит: он задерживает отдачу той страницы, на которой сработал, а если за время без посетителей скопится несколько агентов, следующий посетитель получит страницу заметно медленнее. Для ресурсоёмких задач стоит переносить выполнение на cron через файл /bitrix/php_interface/cron_events.php.
Как узнать, что агент уже зарегистрирован, и не создать дубль?
Перед вызовом CAgent::AddAgent стоит проверить наличие агента через CAgent::GetList с фильтром по полям NAME и MODULE_ID. Если запись уже есть, повторную регистрацию делать не нужно. Ещё надёжнее вызывать AddAgent не в коде, который выполняется на каждой странице сайта, а разово, например в методе установки модуля.
Можно ли обращаться к REST-методам Битрикс24 из такого агента?
Технически да, агент это обычная PHP-функция и может делать HTTP-запросы к REST API Битрикс24 через вебхук или приложение. Но стоит помнить про ограничения контекста внутри агента: переменной USER там нет, авторизация через Authorize недоступна, а константа SITE_ID не определена, поэтому логику, завязанную на текущего пользователя или сайт, внутри агента строить не получится.