1С Битрикс · 7 мин чтения

CAgent::AddAgent: как создать агента Битрикс прямо из кода

Агенты в 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 не определена, поэтому логику, завязанную на текущего пользователя или сайт, внутри агента строить не получится.

Есть задача?

Обсудим в мессенджере

Расскажите, что нужно сделать — отвечу в течение 4 часов в рабочее время. Первая консультация бесплатно.

Продолжая пользование настоящим сайтом Вы выражаете своё согласие на обработку Ваших персональных данных (файлов куки) с использованием Yandex.Metrika.
Понятно