Жизненный цикл JavaScript-сценария

Сценарий начинается в редакторе и проходит несколько разных состояний. Понимание этого порядка помогает менять сбор без риска для уже работающих данных.

1. Создание и входная точка

При создании сценария выберите сайт и язык JavaScript. Платформа сохранит исходный текст как версию сценария. Точкой входа служит функция run; она получает только объект ctx с разрешёнными методами SDK.

async function run(ctx) {
  const url = ctx.param('catalog_url', '');
  if (!url) ctx.abort('Укажите адрес каталога');
  const response = await ctx.http().get(url);
  if (!response.ok()) ctx.fail(`Сайт ответил HTTP ${response.status}`);
  ctx.emit({ url, title: response.dom().text('h1', '') }, url);
}

Функция может вызывать ваши обычные вспомогательные функции. ctx создаётся отдельно для каждого запуска. Нельзя переносить живой объект ctx, открытую страницу браузера или переменную JavaScript из одного прогона в другой. Для небольшого курсора используйте состояние, а для результатов — ctx.emit().

2. Проверка кода

Сохраните черновик и запустите проверку. Она обнаруживает синтаксические ошибки, недопустимую точку входа и часть ошибок структуры, но не доказывает, что CSS-селектор найдёт товар на реальном сайте. У JavaScript нет пошаговой отладки с точками останова: наблюдайте за пробным прогоном, журналом, прогрессом и полученными записями.

Проверка не публикует версию и не запускает сбор. Исправление кода создаёт новый черновик версии; опубликованная версия продолжает работать отдельно.

3. Пробный прогон

Проба исполняет выбранный черновик через ту же JavaScript-песочницу и методы SDK. Записи идут в предпросмотр и не заменяют рабочий каталог. Проверьте количество товаров, ключи, цены, пропуски, журнал запросов и сообщения об ошибках. Для большого каталога начните с одной страницы и небольшого числа карточек.

Параметры берутся из сайта, настроек сценария и конкретного запуска. Читайте их через ctx.param() или ctx.params(). Секреты сайта читайте через await ctx.credential(name) и никогда не выводите в журнал или emit().

4. Публикация и рабочие запуски

После успешной проверки опубликуйте нужную версию. Публикация переключает рабочую версию сценария, но сама не создаёт прогон. Ручной запуск и расписание используют опубликованный код. Черновик нельзя запустить в боевой каталог; для него есть проба. Если новое изменение ошибочно, можно вернуть ранее опубликованную версию.

Каждый рабочий прогон получает собственный идентификатор, параметры, журнал и статус. ctx.emit(record, key) передаёт запись системе. Постоянный ключ помогает обновлять тот же товар при следующем запуске. ctx.flush() досылает накопленную пачку; в конце успешного или ошибочного завершения буфер также отправляется. Передача записи ещё не означает, что весь прогон завершился: дождитесь итогового статуса и проверьте результат.

5. Что происходит во время run

JavaScript исполняется в отдельной изолированной среде. Обычные вычисления (ctx.text(), ctx.dom(), ctx.url(), разбор уже полученного ответа) выполняются локально. Запросы к сайту, браузеру, хранилищу, документам, почте, состоянию и AI проходят через платформу и возвращают Promise. Их нужно ожидать через await. Не оставляйте незавершённый запрос без await: функция может закончиться раньше результата.

Прямые fetch, require, доступ к файловой системе и запуск команд недоступны. Это ограничение применяется к коду сценария. Для HTTP используйте HttpClient, для интерактивного сайта — BrowserPage. Браузерную страницу закрывайте в finally, даже когда действие вызвало ошибку.

async function run(ctx) {
  const page = await ctx.browser().open(ctx.param('catalog_url'));
  try {
    await page.click('button.show-products');
    await page.waitFor('.product-card');
    const dom = ctx.dom(await page.content());
    for (const card of dom.qa('.product-card')) {
      const sku = card.attr('data-sku');
      if (sku) ctx.emit({ sku, title: card.q('.title')?.text() ?? '' }, sku);
    }
  } finally {
    await page.close();
  }
}

6. Остановка, ошибка и повтор

В длинном цикле вызывайте await ctx.cancelled() и прекращайте работу, когда пользователь остановил прогон. ctx.abort(reason) завершает его осознанной остановкой; ctx.fail(reason) сообщает об ошибке. Непойманная ошибка JavaScript также завершит прогон с ошибкой и попадёт в журнал. Не скрывайте её пустым catch, иначе можно получить неполный набор данных без объяснения.

Если нужно повторить обработку после сбоя, используйте стабильные ключи записей и храните номер последней обработанной страницы в ctx.state(). Состояние рассчитано на небольшой курсор; товары и файлы отправляйте в записи или подключённое хранилище. При повторе проверяйте, что страница действительно новая: один и тот же HTML после кнопки «Далее» не должен бесконечно записываться заново.

7. Агент, лимиты и стоимость

Сценарий можно исполнять на подходящем агенте, если при его создании включён JavaScript. Агент только с PHP не запустит JavaScript-сценарий. Браузерные действия требуют отдельной поддержки браузера на выбранном агенте. При автономной работе доступность отдельных сервисов платформы может ограничиваться; не стройте регулярный сбор на обязательном AI-вызове.

Время обработки и использование AI учитываются по правилам пространства. Локальная обработка текста, HTML и массивов не вызывает отдельный платный AI-запрос. Намеренная пауза ctx.sleep() входит во время выполнения; ожидание готового источника при его защитной задержке учитывается по правилам готового решения. Перед массовым запуском проверьте лимиты и стоимость на короткой пробе.

Справочник Context · Примеры обхода страниц · Прогоны и ошибки