Выполнение и проект

Эти функции либо запускают другой код, либо меняют состояние текущего выполнения или всего проекта. Они используют общую запись функций in-Line, но результат у них бывает трёх разных видов: текст, пустая строка или побочное действие.

Что выбрать

Запрос к серверному сценарию: SCRIPT

SCRIPT отправляет запрос GET на сервер, чей адрес и порт заданы в настройках программы. Содержимое функции становится частью адреса после /.

(|SCRIPT|health?account=42|SCRIPT|)

Если сервер вернул:

ok

функция вернёт ok. Конечные пробельные символы ответа удаляются, но реализация оставляет хотя бы один символ даже у ответа, состоящего только из пробелов.

(|SCRIPT|validate?login=(|URLENCODE||LOGIN||URLENCODE|)|SCRIPT|)

Не добавляйте начальный /: исполнитель уже вставляет его между адресом сервера и аргументом. Если соединение не удалось, функция возвращает строку, начинающуюся с Synapse System Error - , поэтому такой текст нужно считать ошибкой запроса, а не ответом прикладного сценария.

Выполнение JavaScript: EVAL

EVAL сначала подставляет вложенные значения, затем выполняет полученный JavaScript в общем контексте QuickJS без модулей ES. Результат последнего вычисленного выражения становится результатом функции.

(|EVAL|6 * 7|EVAL|)

Результат:

42

Полный состав объекта PK, правила общего контекста и ограничения среды находятся в справочнике JavaScript.

Для принудительного запуска прежнего движка добавьте служебную метку |USEOLDJS| внутрь аргумента:

(|EVAL||USEOLDJS|(function () { return 6 * 7; })()|EVAL|)

Перед выполнением метка удаляется. Используйте её только для кода, который действительно зависит от прежнего движка: без метки применяется QuickJS, а при недоступности QuickJS исполнитель сам обращается к прежнему движку.

Выполнение блока сценария: SCRIPTBOX

SCRIPTBOX запускает содержимое по правилам блока сценария и возвращает пустую строку. Его удобно использовать как внешнюю функцию, когда требуется выполнить несколько строк, присваивания, условия или циклы.

(|SCRIPTBOX|
|DV|[state] = ready
|DV|[attempt] = 1
|SCRIPTBOX|)

После выполнения |DV|[state] равно ready, |DV|[attempt] равно 1, а сама функция ничего не вставляет в окружающий текст. Синтаксис строк, циклов, критической секции и результатов разобран в руководстве по SCRIPTBOX.

Вызов внешней библиотеки: DLL

DLL находит уже загруженную библиотеку и вызывает экспортированную из неё функцию. Имя файла указывается без .dll, а параметры разделяются меткой |PDEL|.

(|DLL|dllName:myDll;funcName:myFunc;params:first|PDEL|second;|DLL|)

Точные имена полей:

Имя библиотеки и имя функции выбираются до подстановки вложенных значений. В самих параметрах переменные и функции выполняются после того, как библиотека и экспорт уже найдены.

Поле называется именно params. Запись parametrs из прежней справки не соответствует исполнителю.

Для отображения сведений о библиотеке в обзоре она может дополнительно экспортировать info_getAuthor, info_getVersion и info_getDescription. Эти функции не требуются для прямого вызова через DLL.

Ожидание текущего выполнения: SLEEP

SLEEP задерживает только текущее выполнение на указанное число миллисекунд и возвращает пустую строку. Другие параллельные выполнения проекта продолжают работать.

(|SLEEP|500|SLEEP|)

Этот вызов ждёт примерно половину секунды. Значение 0 допустимо и не создаёт задержки.

Передавайте только десятичные цифры. Текущий исполнитель удаляет из аргумента все остальные символы перед преобразованием: -100 фактически становится 100, а wait500ms — 500. Если после удаления не осталось цифр, преобразование завершается ошибкой. Такое исправление ввода не является частью надёжного договора, поэтому не полагайтесь на него.

Полная остановка: STOP

STOP останавливает весь проект и может показать переданное сообщение. Вложенные значения в сообщении подставляются до остановки.

(|STOP|Превышен допустимый предел ошибок|STOP|)

Функция возвращает тот же текст, который передан внутрь, но её основное назначение — остановка проекта. Текст может успеть попасть в окружающее выражение, поэтому не используйте возвращаемое значение как признак того, что последующие действия будут выполнены.

Пауза до ручного продолжения: PAUSE

PAUSE переводит весь проект на паузу и может показать причину оператору. Продолжение выполняется вручную.

(|PAUSE|Проверьте ответ перед продолжением|PAUSE|)

Как и STOP, функция возвращает переданное сообщение. Побочное действие ставится в очередь только один раз для текущего состояния проекта, поэтому повтор текста не означает повторного перехода на паузу.

Пауза на заданное время: PAUSEFOR

PAUSEFOR приостанавливает весь проект и автоматически продолжает его после заданного времени. Аргумент — целое число миллисекунд от 1 до 86400000.

(|PAUSEFOR|30000|PAUSEFOR|)

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

Ручное продолжение, остановка, закрытие проекта, сброс или новая PAUSEFOR отменяют прежнее автоматическое продолжение. Значение должно состоять только из цифр: пробелы, знак и дробная часть завершают вызов явной ошибкой.

Настройки работающего проекта

PROJECTSETTING читает текущее значение настройки того проекта, в котором выполняется Скрипт-бокс. SETPROJECTSETTING изменяет поддерживаемую настройку этого же проекта. Обе функции недоступны вне работающего проекта и не могут обращаться к другому запуску или произвольному элементу формы.

Чтение настройки: PROJECTSETTING

Передайте точный идентификатор настройки между парными метками:

|PROJECTSETTING|threads|PROJECTSETTING|

Результат всегда является строкой. Для примера выше это будет текущее число потоков, например 50. Идентификаторы и имена динамических настроек чувствительны к регистру.

Изменение настройки: SETPROJECTSETTING

Аргументом служит JSON-объект ровно с двумя строковыми полями name и value:

|SETPROJECTSETTING|{"name":"timeout_seconds","value":"30"}|SETPROJECTSETTING|

После обычного изменения функция возвращает applied. Для threads она может вернуть scheduled: Keeper ставит проект на штатную паузу, заново подготавливает рабочую базу под выбранное число потоков и безопасно продолжает работу. Если ресурсов недостаточно, изменение не применяется частично и возвращается ошибка.

Встроенные настройки

Динамические настройки автора

Динамическая настройка указывается как dynamic: и её точное название:

|PROJECTSETTING|dynamic:Регион|PROJECTSETTING|
|SETPROJECTSETTING|{"name":"dynamic:Регион","value":"Киев"}|SETPROJECTSETTING|

Обычное поле и многострочное поле принимают любой текст. Флажок и переключатель принимают только true или false. Список принимает точную подпись одного из своих пунктов с учётом регистра. Название должно однозначно соответствовать одной динамической настройке проекта.

Идентификаторы: ADDID и DELID

Идентификаторы участвуют в выборе результата текущего выполнения. Эти функции меняют рабочий список, не создавая отдельную копию для вызова.

(|ADDID|GOOD1|ADDID|)

Управление прокси

Функции этого раздела работают с прокси текущего выполнения. Удаление или временная блокировка адреса не выбирает следующий адрес автоматически.

(|USEPROXY|login:[email protected]:1080,SOCKS5|USEPROXY|)

IP:PORT
IP:PORT:LOGIN:PASSWORD
LOGIN:PASSWORD@IP:PORT

Обычная последовательность после запрета адреса выглядит так:

#beginScript
(|FREEZEPROXY|180|FREEZEPROXY|)
|DV|[selectedProxy] = (|NEXTPROXY||NEXTPROXY|)
#endScript

После FREEZEPROXY требуется отдельный NEXTPROXY; иначе текущий запросный узел продолжит хранить прежний адрес.

Вывод в студии: PRINT

PRINT подставляет вложенные значения, записывает сообщение в журнал студии и возвращает исходный текст без изменений.

(|PRINT|Блок выполнен успешно|PRINT|)

В студии журнал получает сообщение Блок выполнен успешно, а результат функции также равен Блок выполнен успешно. В обычном запуске без журнала студии запись не создаётся, но текст всё равно возвращается.

Статус: (|PRINT|готово|PRINT|)

Результат окружающего выражения — Статус: готово. Не выводите через PRINT пароли, ключи доступа и другие секреты: журнал предназначен для диагностики и может сохраняться вместе с рабочими материалами.

Время Unix в дату: UNIXTODATE

UNIXTODATE принимает целое число секунд от начала эпохи Unix и возвращает дату во времени UTC. Без второго поля используется вид dd/mm/yy.

(|UNIXTODATE|1571994528|UNIXTODATE|)

Результат:

25/10/19

Собственный вид отделяется одной вертикальной чертой:

(|UNIXTODATE|1753172299|yyyy-mm-dd"T"hh:nn:ss|UNIXTODATE|)

Результат:

2025-07-22T08:18:19

Используйте nn для минут: mm обозначает месяц. Полный перечень обозначений приведён в официальном справочнике FormatDateTime.

Число должно быть десятичным целым типа Int64 без окружающих пробелов. Поддерживаемый промежуток — от -59011459200 до 253402300799, то есть даты с 0100 по 9999 год. Собственный вид не может быть пустым и не может содержать ещё одну вертикальную черту.

Сохранение файла: SAVEFILE

SAVEFILE сохраняет текст в UTF-8 или декодирует Base64 в байты. Обычный относительный путь отсчитывается от каталога результатов текущего сеанса.

(|SAVEFILE|reports\result.txt|overwrite|text|Состояние: готово|SAVEFILE|)

Поля разделяются вертикальной чертой:

имя файла|действие|данные
имя файла|действие|text|данные
имя файла|действие|bytes|данные Base64

Только поле данных выполняется как in-Line. Имя файла, действие и тип являются статическими строками: переменная в имени файла не подставится.

(|SAVEFILE|reports\response.json|overwrite|text||RESPONSE||SAVEFILE|)

Здесь вычисляется |RESPONSE|, а путь reports\response.json остаётся неизменным. Вертикальные черты внутри вычисленных данных сохраняются: после служебных полей исполнитель соединяет все оставшиеся части обратно.

Названия действий и типов не зависят от регистра. Если третье поле равно text или bytes и после него есть ещё одно поле, оно считается типом. Поэтому данные, которые буквально начинаются с text|, записывайте в явной форме:

(|SAVEFILE|reports\literal.txt|overwrite|text|text|continued|SAVEFILE|)

В файл попадёт text|continued.

Косая черта / в имени заменяется на \. Абсолютный путь с буквой диска поддерживается, если в нём нет ..\, но привязывает сценарий к конкретному компьютеру. Сетевой путь вида \\server\share не принимается как допустимый абсолютный путь.

В студии каталог сеанса отсутствует: после проверки аргументов функция возвращает Success (in studio you can't save files) и не создаёт файл. Поэтому наличие этой строки в студии не является доказательством записи.

Ошибки создания каталога, записи и декодирования Base64 возвращаются как текст функции. Разветвляйте сценарий по ожидаемой строке успеха и сохраняйте сообщение ошибки для диагностики; не считайте любой непустой результат успешным.